Crate micromegas_tracing

Tracing crate

Provides logging, metrics, memory and performance profiling

Have the lowest impact on the critical path of execution while providing great visibility, tracing focusses on providing predictable performance for high performance applications. It was originaly designed for video game engines.

Contrary to other tracing crates, tracing does not provide hooks for individual events but rather a stream of events, internally it leverages transit to serialize the events into a binary format. meant to be consumed later on in process but can also be sent efficiently over the wire.

Examples

use micromegas_tracing::{
   span_scope, info, warn, error, debug, imetric, fmetric, guards, event,
};

// Initialize tracing, here with a null event sink, see `lgn-telemetry-sink` crate for a proper implementation
// libraries don't need (and should not) setup any TracingSystemGuard
let _tracing_guard = guards::TracingSystemGuard::new(
    8 * 1024 * 1024,
    1024 * 1024,
    16 * 1024 * 1024,
    std::sync::Arc::new(event::NullEventSink {}),
    std::collections::HashMap::new(),
);
let _thread_guard = guards::TracingThreadGuard::new();

// Create a span scope, this will complete when the scope is dropped, and provide the time spent in the scope
// Behind the scene this uses a thread local storage
// on an i9-11950H this takes around 40ns
span_scope!("main");

// Logging
info!("Hello world");
warn!("Hello world");
error!("Hello world");
debug!("Hello world");

// Metrics
imetric!("name", "unit", 0);
fmetric!("name", "unit", 0.0);

Modules

dispatch

Where events are recorded and eventually sent to a sink

errors

event

Structure to record events in memory

flush_monitor

FlushMonitor triggers the flush of the telemetry streams at regular interval.

guards

RAII-style guards

intern_string

Store dynamically-created strings in a global container. Strings are never released from the container.

levels

Verbosity management

logs

Events representing a process’s log

metrics

Events representing a measured scalar at a point in time

panic_hook

Reports panics as fatal log entries and shuts down the telemetry system

parsing

Manual parsing of dynamically sized events

prelude

process_info

Process metadata

property_set

Interned collection of PropertySet instances. Each PropertySet contains properties where the names and the values are statically allocated. The user is expected to manage the cardinality.

spans

Events reprensenting units of code execution

static_string_ref

StaticStringRef points to a string dependency keeping track of the codec. Necessary for unreal instrumentation where ansi and wide strings can coexist. In cases where the event format does not have to be compatible with unreal, StringId can be used.

string_id

StringId serializes the value of the pointer and the size of a UTF8 string. StaticStringRef should be prefered where wire compatibility with unreal is important.

time

System & monotonic tick count

Macros

async_span_scope

async_span_scope is not supported yet

async_span_scope_named

async_span_scope_named is not supported yet

debug

Logs a message at the debug level.

error

Logs a message at the error level.

fatal

Logs a message representing a crash or panic

fmetric

Records a float metric.

imetric

Records a integer metric.

info

Logs a message at the info level.

log

The standard logging macro.

log_enabled

Determines if a message logged at the specified level in that module will be logged.

span_scope

Records a sync span as two thread events

span_scope_named

Records a span with a name that is determined at runtime. The span name still needs to be statically allocated.

trace

Logs a message at the trace level.

warn

Logs a message at the warn level.