Diagnosticism.Rust

Diagnosticism, for Rust

Introduction

Diagnosticism is a library providing miscellaneous discrete and simple diagnostics facilities to supplement what is available in the standard library. It implemented in several languages, providing enhancements that are necessary (and possible). For example, Diagnosticism.Python can provide the trace() function that can capture the callstack information to issue into a diagnostic log statement.

In Rust, which has many powerful reflective and diagnostic elements built in, the facilities are (currently) aimed around supplementing the std::fmt::Debug trait. For example, the Ellipsis component is able to be used in a custom Debug implementation for a given type to elide certain aspects of the instance's state that is not of interest in the logs or, perhaps, to elide with "{:?}" but still include in "{:#?}" (the #alternate() form). (See the Examples section below for more on this.)

Other facilities (that are not directly related to Debug) will be added to the crate soon (and will be listed in the Components section below).

Table of Contents

• Introduction
• Installation
• Components
  • Constants
  • Enumerations
  • Features
  • Functions
  • Macros
  • Structures
  • Traits
• Examples
  • Example - DoomGram
  • Example - Ellipsis
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Dev Dependencies
  • Related projects
  • License

Installation

Reference in Cargo.toml in the usual way:

diagnosticism = { version = "0" }

Components

Constants

No public constants are defined at this time.

Enumerations

No public enumerations are defined at this time.

Features

No public crate-specific features are defined at this time.

Functions

No public functions are defined at this time.

Macros

No public macros are defined at this time.

Structures

The following structures are defined:

• DebugSqueezer - used to assist with restricting the length of Debug forms of fields within a given width;
• DoomGram - a Decimal Order-Of-Magnitude histoGram structure that records efficiently duration values in the orders of magnitude 1ns+, 10ns+, 100ns+, 1µs+, ..., 10s+, 100s+ and provides a mechanism for displaying this histogram in a simple single 12-character display, which is useful for logging cumulative execution costs of components in long-running performance-sensitive applications;
• Ellipsis - provides strings such as "********" to be used for fields that are sensitive and whose Debug forms are not to be expressed;
• Password - Simple type that provides the string "..." to be used for fields whose Debug forms are not to be expressed;

Traits

No public traits are defined at this time.

Examples

Example - DoomGram

The example program doomgram (in examples directory, built with feature test-doomgram), illustrates use of DoomGram to capture the order-of-magnitude histogram of a large number of small random delays. The program source is:

// examples/doomgram.rs : example program illustrating use of `DoomGram`

use diagnosticism::diagnostics::DoomGram;

use rand::{
    rngs::StdRng,
    RngCore,
    SeedableRng,
};

use std::{
    thread,
    time::{
        Duration,
        Instant,
    },
};


fn main() {
    let mut rng = <StdRng as SeedableRng>::seed_from_u64(123456789);

    let mut dg = DoomGram::default();

    // do a warmup loop first
    for w in 0..2 {
        for i in 0..20000 {
            let mut v = rng.next_u32() % 1000000;

            if 0 == i % 10 {
                if 0 != i {
                    v = v % i;
                }
            }

            let before = Instant::now();

            if 0 != i % 2000 {
                thread::sleep(Duration::from_nanos(v as u64));
            } else {
                // no wait, so should be very low ns

                thread::sleep(Duration::from_secs(0));
            }

            let after = Instant::now();

            dg.push_event_duration(after - before);
        }

        // output results on second run through
        if 1 == w {
            let before = Instant::now();
            let strip = dg.to_strip();
            let after = Instant::now();

            eprintln!("`#to_strip()` : {strip} (in {:?})", after - before);
            eprintln!("");
            eprintln!("dg={dg:#?}");
        }

        dg.clear();
    }
}

and a typical output is:

`#to_strip()` : _aabdedba___ (in 1.763µs)

dg=DoomGram {
    event_count: 20000,
    event_time_total: 12881133711,
    has_overflowed: false,
    min_event_time: Some(
        59,
    ),
    max_event_time: Some(
        197384416,
    ),
    num_events_in_1ns: 0,
    num_events_in_10ns: 3,
    num_events_in_100ns: 7,
    num_events_in_1us: 56,
    num_events_in_10us: 3000,
    num_events_in_100us: 13222,
    num_events_in_1ms: 3687,
    num_events_in_10ms: 23,
    num_events_in_100ms: 2,
    num_events_in_1s: 0,
    num_events_in_10s: 0,
    num_events_ge_100s: 0,
}

showing the exploded Debug form of the DoomGram instance and its timing strip that, for particular execution, obtains the value "_aabdedba___" that indicates that there have been:

• 0 events in the 1ns+, 1s+, 10s+, 100s+ magnitudes;
• 1-9 events in 10ns+, 100ns+, 100ms+ magnitudes;
• 10-99 events in 1µs+, 10ms+ magnitudes;
• 1000-9999 events in 10µs+, 10ms+ magnitudes;
• 10000-99999 events in the 100µs+ magnitude;

Naturally, in a live system one would not be employing the exploded Debug view, relying only on the terse and efficient timing strip format.

Example - Ellipsis

In the example program ellipsis (in examples directory), the following types are defined to illustrate the benefit of using Ellipsis to provide concise Debug output in terse (i.e. non-#alternate()) form:

/// Large structure that provides the internals of `Thing`
#[derive(Clone)]
#[derive(Debug)]
struct LargeInternal {
    f1 : i64,
    f2 : f32,
    f3 : BTreeMap<&'static str, &'static str>,
    f4 : BTreeSet<u64>,
    f5 : Vec<HashMap<BTreeMap<i32, String>, BTreeSet<u64>>>,
}

#[derive(Debug)]
struct Thing1 {
    name : String,
    internals : Option<LargeInternal>,
}

struct Thing2 {
    name : String,
    internals : Option<LargeInternal>,
}

impl std::fmt::Debug for Thing2 {
    fn fmt(
        &self,
        f: &mut std::fmt::Formatter<'_>,
    ) -> std::fmt::Result {

        if f.alternate() {
            f
                .debug_struct("Thing2")
                .field("name", &self.name)
                .field("internals", &self.internals)
                .finish()
        } else {
            let ellipsis = Ellipsis::default();

            f
                .debug_struct("Thing2")
                .field("name", &self.name)
                .field("internals", &ellipsis)
                .finish()
        }
    }
}

and the program's output illustrates these differing forms, as shown in this filtered form:

Terse `Debug` form of `thing1`: Thing1 { name: "i-am-a-public-thing", internals: Some(LargeInternal { f1: -123, f2: -3.4028235e38, f3: {"a": "A", "b": "B", "c": "C", "d": "D", "e": "E", "f": "F"}, f4: {1, 2, 4, 11, 12345678}, f5: [] }) }

Terse `Debug` form of `thing2`: Thing2 { name: "i-am-a-public-thing", internals: ... }

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/Diagnosticism.Rust.

Dependencies

Diagnosticism.Rust has no (non-development) dependencies.

Dev Dependencies

Crates upon which Diagnosticism.Rust has development dependencies:

• criterion;
• test_help-rs;

Related projects

• Diagnosticism.Python;

License

Diagnosticism.Rust is released under the 3-clause BSD license. See LICENSE for details.