1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
//! # High-Performance Distributed Tracing Module
//!
//! Focuses on trace_id generation, propagation, and management, providing W3C TraceContext compliant
//! tracing ID solutions. Core functionality is web framework agnostic, with out-of-the-box
//! middleware support for Axum.
//!
//! ## Core Features
//!
//! - **High Performance**: Uses timestamp + atomic counter + machine ID combination, avoiding UUID generation overhead
//! - **W3C Compliant**: Generates 128-bit trace-id compliant with W3C TraceContext specification
//! - **Async Friendly**: Context management based on tokio::task_local, supporting ID propagation between async tasks
//! - **Framework Agnostic**: Core functionality doesn't depend on specific web frameworks
//! - **Axum Integration**: Provides out-of-the-box middleware and extractors
//!
//! ## Basic Usage
//!
//! ### Generating and Using TraceId
//! ```
//! use trace_id::TraceId;
//!
//! // Generate new trace ID (W3C TraceContext compliant)
//! let trace_id = TraceId::new();
//! println!("Generated trace ID: {}", trace_id);
//!
//! // Create from string (with validation)
//! let valid_id = "0af7651916cd43dd8448eb211c80319c";
//! if let Some(trace_id) = TraceId::from_string_validated(valid_id) {
//! println!("Valid trace ID: {}", trace_id);
//! }
//! ```
//!
//! ### Context Management
//! ```
//! use trace_id::{TraceId, with_trace_id, get_trace_id};
//!
//! async fn some_async_function() {
//! // Get current trace ID in async context
//! let current_id = get_trace_id();
//! println!("Current trace ID: {}", current_id);
//! }
//!
//! #[tokio::main]
//! async fn main() {
//! let trace_id = TraceId::new();
//!
//! // Execute async operations within specified trace context
//! with_trace_id(trace_id, async {
//! some_async_function().await;
//! }).await;
//! }
//! ```
//!
//! ## Axum Integration
//!
//! After enabling the `axum` feature, you can use built-in middleware and extractors:
//!
//! ```ignore
//! use axum::{routing::get, Router};
//! use trace_id::{TraceId, TraceIdLayer};
//!
//! async fn handler(trace_id: TraceId) -> String {
//! // Get TraceId directly in function signature
//! format!("Hello! Your trace ID is: {}", trace_id)
//! }
//!
//! #[tokio::main]
//! async fn main() {
//! let app = Router::new()
//! .route("/", get(handler))
//! .layer(TraceIdLayer::new()); // Automatically handle x-trace-id header
//!
//! let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
//! axum::serve(listener, app).await.unwrap();
//! }
//! ```
//!
//! ### Advanced Configuration
//! ```ignore
//! use trace_id::{TraceIdLayer, TraceIdConfig};
//!
//! let config = TraceIdConfig {
//! enable_span: true, // Enable tracing span
//! enable_response_header: true, // Include trace ID in response
//! };
//!
//! let layer = TraceIdLayer::with_config(config)
//! .with_generator(|| uuid::Uuid::new_v4().to_string()); // Custom generator
//! ```
// ================================================================================================
// Module Declarations
// ================================================================================================
/// Trace ID context management module
///
/// Provides async context management functionality based on tokio::task_local
/// Trace ID core struct module
///
/// Contains TraceId struct definition and related implementations
// ================================================================================================
// Public API Exports
// ================================================================================================
/// Re-export context management functions
///
/// - `get_trace_id()`: Get the trace ID of the current async task
/// - `with_trace_id()`: Execute async operations within specified trace context
pub use ;
/// Re-export core trace ID struct
pub use TraceId;
/// Trace ID field name in HTTP headers
///
/// Follows common tracing system conventions, used for passing trace ID in HTTP requests/responses
pub const TRACE_ID_HEADER: &str = "x-trace-id";
// ================================================================================================
// Axum Framework Integration (Optional Feature)
// ================================================================================================
/// Axum framework integration module
///
/// Only available when "axum" feature is enabled
/// Re-export Axum middleware layer
///
/// Provides out-of-the-box trace ID middleware, supporting:
/// - Automatically extract trace ID from request headers
/// - Generate new trace ID (if not present in request)
/// - Add trace ID to response headers
/// - Create tracing span for log correlation
pub use ;