Crate micromegas_tracing

Expand description

High-performance tracing for logs, metrics, and spans.

This crate provides low-overhead instrumentation (~20ns per event) for high-performance applications. Originally designed for video game engines, it focuses on predictable performance while providing comprehensive observability.

§Quick Start - Instrumenting Functions

The easiest way to instrument your code is with the #[span_fn] attribute macro:

use micromegas_tracing::prelude::*;

#[span_fn]
async fn fetch_user(id: u64) -> User {
    // Automatically tracks execution time, even across .await points
    database.get_user(id).await
}

#[span_fn]
fn compute_hash(data: &[u8]) -> Hash {
    // Works for sync functions too
    hasher.hash(data)
}

#[span_fn] is the primary tool for instrumenting async code. It correctly tracks wall-clock time across await points by wrapping the future in an InstrumentedFuture.

§Logging

use micromegas_tracing::prelude::*;

info!("User logged in");
warn!("Connection timeout");
error!("Failed to process request");
debug!("Debug info: {value}");
trace!("Detailed trace");

§Metrics

use micromegas_tracing::prelude::*;

imetric!("requests_total", "count", 1);
fmetric!("response_time", "ms", elapsed_ms);

§Manual Span Scopes

For fine-grained control within a function, use span_scope!:

use micromegas_tracing::prelude::*;

fn process_batch(items: &[Item]) {
    span_scope!("process_batch");

    for item in items {
        span_scope!("process_item");
        // Process each item...
    }
}

§Initialization

Libraries should not initialize tracing - that’s the application’s responsibility. Applications typically use #[micromegas_main] from the micromegas crate, or manually set up guards:

use micromegas_tracing::{guards, event};

// Application initialization (libraries should NOT do this)
let _tracing_guard = guards::TracingSystemGuard::new(
    8 * 1024 * 1024,  // log buffer size
    1024 * 1024,      // metrics buffer size
    16 * 1024 * 1024, // spans buffer size
    std::sync::Arc::new(event::NullEventSink {}),
    std::collections::HashMap::new(),
    true, // Enable CPU tracing
);
let _thread_guard = guards::TracingThreadGuard::new();

§Architecture

Unlike other tracing crates, this library collects events into a stream rather than providing per-event hooks. Events are serialized to a binary format using transit, enabling efficient in-process buffering and network transmission.

Modules§

dispatch: Where events are recorded and eventually sent to a sink
errors: Error types and handling for tracing operations
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: Commonly used items for convenient importing - includes macros, types, and traits
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.
runtime: Runtime integration utilities for micromegas tracing
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.
test_utils: Test utilities for in-memory tracing in unit tests
time: System & monotonic tick count

Macros§

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.
instrument_named: Instruments a future with a named span. Usage: instrument_named!(future, "span_name")
log: The standard logging macro.
log_enabled: Determines if a message logged at the specified level in that module will be logged.
span_async_named: Instruments an async block with a named span using a static string. This creates both the SpanLocation and instruments the future in one macro call.
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.
static_span_desc
static_span_location: Creates a static SpanLocation for use with named async spans. This is an internal implementation detail - users should use instrument_named! instead.
trace: Logs a message at the trace level.
warn: Logs a message at the warn level.