Module Tracing

AirLibrary

Module Tracing 

Source
Expand description

§Distributed Tracing Module

Provides distributed tracing support with trace ID generation, span collection, correlation ID propagation, trace export capabilities, and sampled tracing for performance.

§Responsibilities

§Trace Generation

  • Unique trace ID generation using UUID v4
  • Span ID generation for hierarchical tracing
  • Distributed trace parent-child relationships
  • Trace context propagation across service boundaries

§Span Management

  • Span lifecycle management (started, active, completed, failed)
  • Span attribute and event tracking
  • Duration measurement with microsecond precision
  • Automatic span cleanup with TTL

§Distributed Tracing Integration

  • W3C Trace Context format compatibility
  • Correlation ID propagation for request tracking
  • OpenTelemetry integration support
  • B3 header format support for Zipkin/Jaeger

§Sampled Tracing

  • Trace sampling to avoid performance degradation
  • Configurable sampling rates by endpoint
  • Head-based sampling for high-volume requests
  • Tail-based sampling candidate tracking

§Integration with Mountain

Tracing coordinates with Wind services:

  • Distributed traces across all Element daemons
  • Wind services consume trace data for analysis Real-time trace visualization in Mountain UI
  • Cross-service latency and dependency mapping

§VSCode Debugging References

Similar tracing patterns used in VSCode for:

  • Cross-process communication tracing
  • Extension host performance profiling
  • Language server protocol debugging
  • IPC message flow tracking

Reference: vs/base/common/errors

§Performance Considerations

  • Trace sampling based on request volume and importance
  • Async span storage to avoid blocking service paths
  • Bounded span cache with automatic cleanup
  • Lock-free where possible for high-frequency operations

§TODOs

  • [OPENTELEMETRY] Full OpenTelemetry SDK integration
  • [SAMPLING] Implement dynamic/tail-based sampling
  • [EXPORT] OpenTelemetry Protocol (OTLP) export to Jaeger/Zipkin
  • [ANALYSIS] Automatic anomaly detection in traces
  • [METRICS] Trace-derived custom metrics

§Sensitive Data Handling

Tracing automatically excludes sensitive data:

  • No request payloads in span attributes
  • No authentication tokens in trace headers
  • No user-identifiable information in spans
  • Error messages are sanitized before export

Structs§

PropagationContext
Context propagation information
SamplingConfig
Sampling configuration for trace generation
SpanEvent
Event within a span
TraceGenerator
Trace ID generator and manager with sampling support
TraceMetadata
Distributed trace metadata
TraceSpan
A single span in a trace
TraceStatistics
Trace statistics for monitoring

Enums§

SpanStatus
Span status
TraceStatus
Trace status

Functions§

create_propagation_context
Create a propagation context from a trace span
create_trace_context_header
Create a W3C trace context header from propagation context
get_propagation_context
Get the current propagation context
get_trace_generator
Get or initialize the global trace generator
initialize_tracing
Initialize the global trace generator with custom sampling
set_propagation_context
Set the propagation context for the current thread