tokio-rs/tracing
Tracing
This project is a structured tracing framework for Rust that serves as an async-aware instrumentation library and telemetry data collector. It provides a structured logging facade and the tools necessary to record, filter, and route event-based diagnostic data from both standard applications and embedded systems.
The framework distinguishes itself through a core implementation that supports bare-metal and no-standard-library environments without requiring a dynamic memory allocator. It specifically handles the complexities of asynchronous workflows by propagating diagnostic contexts across futures and tracking execution flow across await points.
Its broader capabilities include span lifecycle management to model execution hierarchy and causal relationships, as well as field-based structured metadata for machine-readable telemetry. The system incorporates a layered middleware composition for data routing and employs severity-based and compile-time filtering to minimize production overhead.
The project also provides interoperability layers to bridge structured telemetry events with traditional logging frameworks.
Features
- Async Task Instrumentation - Attaches spans to futures to maintain diagnostic context every time an asynchronous task is polled or dropped.
- Instrumentation Libraries - Provides an async-aware instrumentation library for tracking execution contexts and spans in Rust.
- Trace Event Emissions - Records structured events at specific severity levels to capture snapshots of program state.
- Bare Metal Diagnostic Tools - Implements a tracing framework capable of running in no-std environments without a dynamic memory allocator.
- No-Std Environment Adapters - Decouples the instrumentation API from the standard library to support bare-metal and embedded environments.
- Bare Metal Development - Supports instrumentation in embedded systems operating without a standard library or dynamic memory allocation.
- Asynchronous Tracing - Tracks execution flow and diagnostic context across await points in asynchronous Rust futures.
- Telemetry Event Dispatchers - Routes instrumentation events and span lifecycles to a set of registered collectors for processing.
- Severity Level Filtering - Controls the volume of collected data by ignoring events and spans based on their severity levels.
- Diagnostic Context Propagators - Implements mechanisms to maintain diagnostic context across asynchronous execution boundaries and threads.
- Execution Context Tracking - Wraps operations in named spans to associate all internal events with a specific logical task.
- Application Diagnostic Data - Collects stability and performance telemetry from running applications to identify bottlenecks through spans and events.
- Telemetry Routing - Filters and forwards structured telemetry to different collectors based on severity or metadata.
- Custom Span Timing - Records periods of time where related events occur using specific attributes and severity levels.
- Lifecycle Management - Tracks execution time and nesting by entering and exiting spans for synchronous or asynchronous scopes.
- Structured Logging - Records machine-readable diagnostic events with key-value pairs to simplify program analysis.
- Structured Log Field Attachments - Provides capabilities for attaching persistent key-value metadata fields to structured log entries.
- Structured Tracing Frameworks - Provides a comprehensive framework for collecting structured, event-based diagnostic and telemetry data.
- Telemetry Collectors - Records, filters, and routes diagnostic spans and events to external telemetry collectors.
- Span Enablement Checks - Verifies if a span is active to avoid performing expensive computations when logging is disabled.
- Metadata Filters - Drops notifications for specific execution periods or events based on metadata to reduce diagnostic noise.
- Embedded Diagnostics - Implements lightweight instrumentation for bare-metal and no-std environments where dynamic memory is unavailable.
- Global Diagnostic Dispatchers - Configures a default handler for diagnostic events for a specific duration or the application lifetime.
- Causal Relationship Modeling - Links spans via associations to model indirect relationships, such as a task spawning background jobs.
- Telemetry Processing Pipelines - Employs a layered middleware composition to filter and route telemetry data in a sequential pipeline.
- Thread-Local Context Management - Uses thread-local storage to track the current active span and maintain execution hierarchy.
- Call-Site Filtering - Evaluates whether an event is enabled before executing metadata computations to minimize production overhead.
- Active Span Context Retrieval - Returns a handle to the currently active span or provides a fallback if the span is disabled.
- Application Performance Monitoring - Measures execution time and nesting of code blocks using spans to identify performance bottlenecks.
- Function Auto-Instrumentation Macros - Automatically enters a diagnostic span upon function entry to capture arguments and return values.
- Compile-Time Instrumentation Filtering - Removes instrumentation for specific diagnostic levels from the binary to reduce production overhead.
- Dynamic Span Field Updates - Assigns or updates values for predefined fields within a span to capture dynamic diagnostic information.
- Logging Framework Bridges - Translates structured events into traditional log records or consumes legacy logs as structured events for compatibility.
- Observability Collectors - Establishes a default diagnostic collector to capture events when no thread-local collector exists.
- Semantic Span Categorization - Assigns names and verbosity levels to spans and events to categorize and group diagnostic data.
- Structured Logging Frameworks - Serves as a facade that translates structured telemetry events into traditional log records.
- Collection Visibility Checks - Determines if a diagnostic event is currently being collected before executing associated logic to save resources.
