micromegas_tracing/
lib.rs

1//! High-performance tracing for logs, metrics, and spans.
2//!
3//! This crate provides low-overhead instrumentation (~20ns per event) for high-performance
4//! applications. Originally designed for video game engines, it focuses on predictable
5//! performance while providing comprehensive observability.
6//!
7//! # Quick Start - Instrumenting Functions
8//!
9//! The easiest way to instrument your code is with the [`#[span_fn]`](prelude::span_fn) attribute macro:
10//!
11//! ```rust,ignore
12//! use micromegas_tracing::prelude::*;
13//!
14//! #[span_fn]
15//! async fn fetch_user(id: u64) -> User {
16//!     // Automatically tracks execution time, even across .await points
17//!     database.get_user(id).await
18//! }
19//!
20//! #[span_fn]
21//! fn compute_hash(data: &[u8]) -> Hash {
22//!     // Works for sync functions too
23//!     hasher.hash(data)
24//! }
25//! ```
26//!
27//! [`#[span_fn]`](prelude::span_fn) is the primary tool for instrumenting async code. It correctly tracks
28//! wall-clock time across await points by wrapping the future in an [`InstrumentedFuture`](prelude::InstrumentedFuture).
29//!
30//! # Logging
31//!
32//! ```rust,ignore
33//! use micromegas_tracing::prelude::*;
34//!
35//! info!("User logged in");
36//! warn!("Connection timeout");
37//! error!("Failed to process request");
38//! debug!("Debug info: {value}");
39//! trace!("Detailed trace");
40//! ```
41//!
42//! # Metrics
43//!
44//! ```rust,ignore
45//! use micromegas_tracing::prelude::*;
46//!
47//! imetric!("requests_total", "count", 1);
48//! fmetric!("response_time", "ms", elapsed_ms);
49//! ```
50//!
51//! # Manual Span Scopes
52//!
53//! For fine-grained control within a function, use [`span_scope!`]:
54//!
55//! ```rust,ignore
56//! use micromegas_tracing::prelude::*;
57//!
58//! fn process_batch(items: &[Item]) {
59//!     span_scope!("process_batch");
60//!
61//!     for item in items {
62//!         span_scope!("process_item");
63//!         // Process each item...
64//!     }
65//! }
66//! ```
67//!
68//! # Initialization
69//!
70//! Libraries should not initialize tracing - that's the application's responsibility.
71//! Applications typically use `#[micromegas_main]` from the `micromegas` crate, or
72//! manually set up guards:
73//!
74//! ```
75//! use micromegas_tracing::{guards, event};
76//!
77//! // Application initialization (libraries should NOT do this)
78//! let _tracing_guard = guards::TracingSystemGuard::new(
79//!     8 * 1024 * 1024,  // log buffer size
80//!     1024 * 1024,      // metrics buffer size
81//!     16 * 1024 * 1024, // spans buffer size
82//!     std::sync::Arc::new(event::NullEventSink {}),
83//!     std::collections::HashMap::new(),
84//!     true, // Enable CPU tracing
85//! );
86//! let _thread_guard = guards::TracingThreadGuard::new();
87//! ```
88//!
89//! # Architecture
90//!
91//! Unlike other tracing crates, this library collects events into a stream rather than
92//! providing per-event hooks. Events are serialized to a binary format using `transit`,
93//! enabling efficient in-process buffering and network transmission.
94//!
95
96// crate-specific lint exceptions:
97#![allow(
98    unsafe_code,
99    missing_docs,
100    clippy::missing_errors_doc,
101    clippy::inline_always
102)]
103
104// dispatch: use wasm version on wasm32
105#[cfg(not(target_arch = "wasm32"))]
106pub mod dispatch;
107#[cfg(target_arch = "wasm32")]
108#[path = "dispatch_wasm.rs"]
109pub mod dispatch;
110
111pub mod errors;
112pub mod event;
113pub mod guards;
114pub mod levels;
115pub mod logs;
116pub mod metrics;
117pub mod panic_hook;
118pub mod process_info;
119pub mod spans;
120pub mod time;
121
122// Native-only: full on native, stubs in lib.rs for wasm32
123#[cfg(not(target_arch = "wasm32"))]
124pub mod property_set;
125
126#[cfg(target_arch = "wasm32")]
127pub mod property_set {
128    /// Stub for EventSink trait compatibility — never constructed on wasm32
129    pub struct Property;
130    /// Stub for dispatch function signatures — never constructed on wasm32
131    pub struct PropertySet;
132}
133
134// Native-only modules (entirely transit-dependent)
135#[cfg(not(target_arch = "wasm32"))]
136pub mod flush_monitor;
137#[cfg(not(target_arch = "wasm32"))]
138pub mod intern_string;
139#[cfg(not(target_arch = "wasm32"))]
140pub mod parsing;
141#[cfg(not(target_arch = "wasm32"))]
142pub mod static_string_ref;
143#[cfg(not(target_arch = "wasm32"))]
144pub mod string_id;
145#[cfg(not(target_arch = "wasm32"))]
146pub mod test_utils;
147
148#[cfg(feature = "tokio")]
149pub mod runtime;
150
151#[cfg_attr(target_arch = "wasm32", allow(unused_imports))]
152#[macro_use]
153extern crate lazy_static;
154
155#[macro_use]
156mod macros;
157
158/// Commonly used items for convenient importing - includes macros, types, and traits
159pub mod prelude {
160    pub use crate::levels::*;
161    pub use crate::process_info::*;
162    #[cfg(feature = "tokio")]
163    pub use crate::runtime::TracingRuntimeExt;
164    #[cfg(feature = "tokio")]
165    pub use crate::spans::spawn_with_context;
166    pub use crate::spans::{
167        InstrumentFuture, InstrumentedFuture, InstrumentedNamedFuture, SpanContextFuture,
168        current_span_id,
169    };
170    pub use crate::time::*;
171    pub use crate::{
172        debug, error, fatal, fmetric, imetric, info, instrument_named, log, log_enabled,
173        span_async_named, span_scope, span_scope_named, static_span_desc, static_span_location,
174        trace, warn,
175    };
176    pub use micromegas_tracing_proc_macros::*;
177}
micromegas_tracing/lib.rs

micromegas_tracing/
lib.rs
