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.

Micromegas Tracing Crate

This crate provides logging, metrics, memory and performance profiling with a low impact on the critical path of execution. It focuses on providing predictable performance for high-performance applications, originally designed for video game engines.

Documentation

• 📖 Complete Documentation
• 🚀 Getting Started Guide
• 💻 GitHub Repository