feat: a more configurable tracing configuration with TracingConfig

Author: davidB

.mise.toml

@@ -16,6 +16,7 @@ protoc = '32.1'
 "aqua:cargo-bins/cargo-binstall" = "1"
 
 [tasks.format]
+alias = "fmt"
 description = "Format the code and sort dependencies"
 run = [
   "cargo fmt",

deny.toml

@@ -213,8 +213,8 @@ skip = [
   # "[email protected]",   # tonic depend on axum 0.7
   # "[email protected]",     # axum 0.7 use tower 0.5, but hyper still use 0.4
   # "sync_wrapper",   # axum direct and transive dependency use multiple version
-  "regex-syntax",
-  "regex-automata",
+  # "regex-syntax",
+  # "regex-automata",
   # "indexmap",
   # "hermit-abi",
   # "rustls-native-certs",

examples/axum-otlp/src/main.rs

@@ -11,7 +11,7 @@ use tracing_opentelemetry_instrumentation_sdk::find_current_trace_id;
 #[tokio::main]
 async fn main() -> Result<(), BoxError> {
     // very opinionated init of tracing, look as is source to make your own
-    let _guard = init_tracing_opentelemetry::tracing_subscriber_ext::init_subscribers()?;
+    let _guard = init_tracing_opentelemetry::TracingConfig::production().init_subscriber()?;
 
     let app = app();
     // run it

examples/grpc/src/client.rs

@@ -13,7 +13,8 @@ pub mod generated {
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // very opinionated init of tracing, look as is source to make your own
-    let _guard = init_tracing_opentelemetry::tracing_subscriber_ext::init_subscribers()
+    let _guard = init_tracing_opentelemetry::TracingConfig::production()
+        .init_subscriber()
         .expect("init subscribers");
 
     // let channel = Channel::from_static("http://[::1]:50051").connect().await?;

examples/grpc/src/server.rs

@@ -48,7 +48,8 @@ impl Greeter for MyGreeter {
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // very opinionated init of tracing, look as is source to make your own
-    let _guard = init_tracing_opentelemetry::tracing_subscriber_ext::init_subscribers()
+    let _guard = init_tracing_opentelemetry::TracingConfig::production()
+        .init_subscriber()
         .expect("init subscribers");
 
     let addr = "0.0.0.0:50051".parse()?;

examples/load/src/main.rs

@@ -7,7 +7,7 @@ use tracing_opentelemetry_instrumentation_sdk::otel_trace_span;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // very opinionated init of tracing, look as is source to make your own
-    let _guard = init_tracing_opentelemetry::tracing_subscriber_ext::init_subscribers()?;
+    let _guard = init_tracing_opentelemetry::TracingConfig::production().init_subscriber()?;
     let mut stats = memory_stats();
     if stats.is_none() {
         eprintln!("Couldn't get the current memory usage :(");

init-tracing-opentelemetry/Cargo.toml

@@ -20,7 +20,9 @@ opentelemetry-otlp = { workspace = true, optional = true, features = [
   "trace",
 ] }
 # opentelemetry-resource-detectors = { workspace = true } //FIXME enable when available for opentelemetry >= 0.25
-opentelemetry-stdout = { workspace = true, features = ["trace"], optional = true }
+opentelemetry-stdout = { workspace = true, features = [
+  "trace",
+], optional = true }
 opentelemetry-semantic-conventions = { workspace = true, optional = true }
 opentelemetry-zipkin = { workspace = true, features = [], optional = true }
 opentelemetry_sdk = { workspace = true }
@@ -39,16 +41,17 @@ tracing-subscriber = { version = "0.3", default-features = false, features = [
 [dev-dependencies]
 assert2 = { workspace = true }
 rstest = { workspace = true }
-# need tokio runtime to run smoke tests.
+# need tokio runtime to run smoke tests and rust doc
+tracing-opentelemetry-instrumentation-sdk = { path = "../tracing-opentelemetry-instrumentation-sdk" }
 opentelemetry_sdk = { workspace = true, features = [
   "trace",
   "rt-tokio",
   "testing",
 ] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+tokio = { version = "1", features = ["full"] }
 tokio-stream = { version = "0.1" }
-tracing-opentelemetry-instrumentation-sdk = { path = "../tracing-opentelemetry-instrumentation-sdk" }
 tracing-subscriber = { version = "0.3", default-features = false, features = [
   "env-filter",
   "fmt",
@@ -72,4 +75,8 @@ tls = ["opentelemetry-otlp/tls", "tonic"]
 tls-roots = ["opentelemetry-otlp/tls-roots"]
 tls-webpki-roots = ["opentelemetry-otlp/tls-webpki-roots"]
 logfmt = ["dep:tracing-logfmt"]
-metrics = ["opentelemetry-otlp/metrics", "tracing-opentelemetry/metrics", "opentelemetry-stdout/metrics"]
+metrics = [
+  "opentelemetry-otlp/metrics",
+  "tracing-opentelemetry/metrics",
+  "opentelemetry-stdout/metrics",
+]

init-tracing-opentelemetry/README.md

@@ -5,21 +5,65 @@
 
 A set of helpers to initialize (and more) tracing + opentelemetry (compose your own or use opinionated preset)
 
-```txt
+```rust
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Simple preset
+    let _guard = init_tracing_opentelemetry::TracingConfig::production().init_subscriber()?;
+
+    //...
+
+    Ok(())
+}
+```
+
+```rust
 #[tokio::main]
-async fn main() -> Result<(), axum::BoxError> {
-    // very opinionated init of tracing, look as is source to compose your own
-    let _guard = init_tracing_opentelemetry::tracing_subscriber_ext::init_subscribers()?;
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // custom configuration
+    let _guard = init_tracing_opentelemetry::TracingConfig::default()
+        .with_json_format()
+        .with_stderr()
+        .with_log_directives("debug")
+        .init_subscriber()?;
 
-    ...;
+    //...
 
     Ok(())
 }
 ```
 
-The `init_subscribers` function returns a `OtelGuard` instance. Following the guard pattern, this struct provides no functions but, when dropped, ensures that any pending traces/metrics are sent before it exits. The syntax `let _guard` is suggested to ensure that Rust does not drop the struct until the application exits.
+The `init_subscriber()` function returns an `OtelGuard` instance. Following the guard pattern, this struct provides no functions but, when dropped, ensures that any pending traces/metrics are sent before it exits. The syntax `let _guard` is suggested to ensure that Rust does not drop the struct until the application exits.
+
+## Configuration Options
+
+### Presets
+
+- `TracingConfig::development()` - Pretty format, stderr, with debug info
+- `TracingConfig::production()` - JSON format, stdout, minimal metadata
+- `TracingConfig::debug()` - Full verbosity with all span events
+- `TracingConfig::minimal()` - Compact format, no OpenTelemetry
+- `TracingConfig::testing()` - Minimal output for tests
+
+### Custom Configuration
+
+```rust,no_run
+use init_tracing_opentelemetry::TracingConfig;
+
+TracingConfig::default()
+    .with_pretty_format()           // or .with_json_format(), .with_compact_format()
+    .with_stderr()                  // or .with_stdout(), .with_file(path)
+    .with_log_directives("debug")   // Custom log levels
+    .with_line_numbers(true)        // Include line numbers
+    .with_thread_names(true)        // Include thread names
+    .with_otel(true)                // Enable OpenTelemetry
+    .init_subscriber()
+    .expect("valid tracing configuration");
+```
+
+### Legacy API (deprecated)
 
-To configure opentelemetry tracer & tracing (& metrics), you can use the functions from `init_tracing_opentelemetry::tracing_subscriber_ext`, but they are very opinionated (and WIP to make them more customizable and friendly), so we recommend making your composition, but look at the code (to avoid some issue) and share your feedback.
+For backward compatibility, the old API is still available:
 
 ```txt
 pub fn build_loglevel_filter_layer() -> tracing_subscriber::filter::EnvFilter {
@@ -150,12 +194,12 @@ spec:
 
 - check you only have a single version of opentelemtry (could be part of your CI/build), use `cargo-deny` or `cargo tree`
 
-    ```sh
-    # Check only one version of opentelemetry should be used
-    # else issue with setup of global (static variable)
-    # check_single_version_opentelemtry:
-    cargo tree -i opentelemetry
-    ```
+  ```sh
+  # Check only one version of opentelemetry should be used
+  # else issue with setup of global (static variable)
+  # check_single_version_opentelemtry:
+  cargo tree -i opentelemetry
+  ```
 
 - check the code of your exporter and the integration with `tracing` (as subscriber's layer)
 - check the environment variables of opentelemetry `OTEL_EXPORTER...` and `OTEL_TRACES_SAMPLER` (values are logged on target `otel::setup` )
@@ -173,7 +217,7 @@ Configure the following set of environment variables to configure the metrics ex
 - `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` override to `OTEL_EXPORTER_OTLP_PROTOCOL`, fallback to auto-detection based on ENDPOINT port
 - `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` to set the timeout for the connection to the exporter
 - `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` to set the temporality preference for the exporter
-- `OTEL_METRIC_EXPORT_INTERVAL` to set frequence of metrics export in __*milliseconds*__, defaults to 60s
+- `OTEL_METRIC_EXPORT_INTERVAL` to set frequence of metrics export in **_milliseconds_**, defaults to 60s
 
 ## Changelog - History