Module tracing 

Copyright © 2025-2026 Wenze Wei. All Rights Reserved.

This file is part of DMSC. The DMSC project belongs to the Dunimd Team.

Licensed under the Apache License, Version 2.0 (the “License”); You may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Distributed Tracing

This file implements a comprehensive distributed tracing system for the DMSC framework. It provides tools for creating, managing, and propagating trace information across asynchronous operations and distributed systems. The tracing system follows the W3C Trace Context standard and integrates with tokio’s context propagation mechanism.

Key Components

• DMSCSpanId: Unique identifier for a span
• DMSCTraceId: Unique identifier for a trace
• DMSCSpanKind: Enumeration of span types (Server, Client, Producer, Consumer, Internal)
• DMSCSpanStatus: Status of a span (Ok, Error, Unset)
• DMSCSpan: A single distributed tracing span with attributes, events, and status
• DMSCSpanEvent: Timed events within a span
• DMSCTracingContext: Thread-local tracing context for propagation
• DMSCTracer: Distributed tracer for creating and managing spans
• DMSCTracerManager: Manager for multiple tracer instances
• DefaultTracerManager: Global tracer manager instance

Design Principles

1. W3C Trace Context Compliance: Follows the W3C Trace Context standard for interoperability
2. Async Context Propagation: Integrates with tokio’s context propagation mechanism
3. Thread Safety: Uses Arc and RwLock for safe concurrent access
4. Sampling Support: Configurable sampling rate to control overhead
5. Hierarchical Spans: Supports parent-child span relationships
6. Baggage Support: Allows carrying contextual information across spans
7. Extensible: Easy to add new span kinds and attributes
8. Low Overhead: Efficient implementation with minimal performance impact
9. Global Access: Provides a global tracer manager for easy access
10. Serialization Support: All tracing components are serializable for export

Usage

use dmsc::observability::{init_tracer, tracer, DMSCSpanKind, DMSCSpanStatus};
use dmsc::core::DMSCResult;

async fn example() -> DMSCResult<()> {
    // Initialize the global tracer with 100% sampling rate
    init_tracer(1.0);
     
    // Get the global tracer
    let tracer = tracer();
     
    // Start a new trace
    let trace_id = tracer.start_trace("example_trace").unwrap();
     
    // Start a child span
    let span_id = tracer.start_span_from_context("child_span", DMSCSpanKind::Internal).unwrap();
     
    // Add an attribute to the span
    tracer.span_mut(&span_id, |span| {
        span.set_attribute("key".to_string(), "value".to_string());
    })?;
     
    // Add an event to the span
    tracer.span_mut(&span_id, |span| {
        let mut attributes = std::collections::HashMap::new();
        attributes.insert("event_key".to_string(), "event_value".to_string());
        span.add_event("example_event".to_string(), attributes);
    })?;
     
    // End the child span with OK status
    tracer.end_span(&span_id, DMSCSpanStatus::Ok)?;
     
    Ok(())
}

Structs

DMSCSpan

A distributed tracing span

DMSCSpanEvent

Span event for recording timed occurrences

DMSCSpanId

Distributed tracing span ID

DMSCTraceId

Distributed tracing trace ID

DMSCTracer

Distributed tracer

DMSCTracerManager

Tracer manager for managing multiple tracer instances

DMSCTracingContext

Thread-local tracing context

DefaultTracerManager

Default tracer manager instance

Enums

DMSCSamplingStrategy

Sampling strategy enumeration

DMSCSpanKind

Span kind enumeration

DMSCSpanStatus

Span status

Statics

DEFAULT_TRACER_MANAGER

Global tracer manager instance

Functions

init_tracer

Initialize global tracer with fixed rate (backward compatibility)

init_tracer_with_strategy

Initialize global tracer with custom sampling strategy

tracer

Get global tracer (backward compatibility)