otel-logger
A tracing and OpenTelemetry integration utility library for Rust applications, providing easy-to-use configuration and initialization capabilities.
otel-logger contains the application logging facade split from tracing-otel in the upcoming release. HTTP helpers are in otel-http. See the migration guide and changelog.
Features
- Easy to Use - Simple configuration of tracing and OpenTelemetry through Builder pattern
- Multiple Output Formats - Support for Compact, Pretty, and JSON formats
- Flexible Configuration - Configure log levels through Logger; sampling and metric export intervals use the SDK environment settings
OTEL_TRACES_SAMPLERandOTEL_METRIC_EXPORT_INTERVAL. - Automatic Resource Cleanup - Automatic management of TracerProvider and MeterProvider through RAII pattern
- Built-in Metrics Support - Integrated OpenTelemetry metrics collection and export
- Environment Detection - Automatic detection of operating system and process information
- OTLP Export - Built-in OTLP protocol support, can directly export to Jaeger, OTEL Collector, etc.
Crate Scope
Logger configures console/file logging, a tracing subscriber, trace and metric
providers, and optional OTLP logs for one process. It is available without any
feature flags. Enable env for Logger::from_env and environment helpers.
otel-logger depends on otel-init with subscriber, and does not depend on
otel-http. Provider-only users can depend directly on otel-init.
Public bootstrap helpers (setup_tracing, init_layer, init_env_filter,
init_tracing_from_logger), default, OtelGuard, and BoxLayer are available
at the crate root. SDK crates are no longer re-exported; use their direct
imports or the existing re-exports in otel-init.
Quick Start
Dependency configuration for the upcoming release:
[]
= "0.34"
= "0.33"
= "0.1"
= { = "1.0", = ["full"] }
= "1"
Basic Usage
use Logger;
use ;
async
Advanced Configuration
use ;
use KeyValue;
use Level;
async
Legacy API (Backward Compatibility)
use init_logging;
async
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
service_name |
String |
otel_logger |
Tracer instrumentation scope name; does not set resource service.name |
format |
LogFormat |
Compact |
Log output format: Compact, Pretty, Json |
ansi |
bool |
true |
Whether to enable ANSI color output |
level |
Level |
INFO |
Log level filtering |
attributes |
Vec<KeyValue> |
[] |
Custom OpenTelemetry attributes |
otel_logs_enabled |
bool |
false |
Whether to enable OpenTelemetry logs export |
Environment Variable Configuration
Enable environment-based Logger configuration with:
= { = "0.34", = ["env"] }
This library supports standard OpenTelemetry environment variables:
# OTLP export endpoint
# If no OTLP endpoint is configured, or it is configured as an empty string,
# tracing and metrics providers are still initialized locally so request spans
# can produce trace IDs, but nothing is exported and no connection to
# localhost:4317 is attempted.
#
# HTTP OTLP options:
# export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
# export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
#
# Specify Protocol for Traces and Metrics:
# export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
# export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json
#
# Without protocol env vars, the native SDK feature default is http/json.
# Set grpc explicitly when using a gRPC receiver (typically port 4317).
# Log level (takes precedence over code configuration)
# Resource attributes
LOG_* settings require the env feature and Logger::from_env(None); they are
library-specific settings, not OpenTelemetry SDK variables. See
environment variable precedence
for SDK resource detection, explicit attribute overrides, and .env loading.
Integration with Axum
Use with axum-otel to achieve complete web service observability:
use ;
use ;
use ServiceBuilder;
use TraceLayer;
use ;
async
async
Resource Cleanup
LoggerGuard implements the RAII pattern and automatically shuts down OpenTelemetry providers, then releases non-blocking file writer guards to trigger their shutdown and flush path. The writer does not report the flush outcome:
// <- guard automatically cleans up resources here
// Manual cleanup is also possible
let guard = new.init?;
// ... use tracing
guard.shutdown?; // Manual cleanup
Requirements
- Rust Version: 1.96.0+
- Tokio Runtime: Requires tokio async runtime
- OTLP Receiver: Need to configure an OTLP-compatible receiver (such as Jaeger, OTEL Collector)
Troubleshooting
Common Issues
-
Failed to connect to OTLP receiver
# Check endpoint configuration # Quickly start Jaeger using Docker -
Log level filtering not working
# Ensure environment variable is set correctly # Or explicitly set level in code ) -
Metrics collection issues
# Collect every 10 seconds; the SDK uses milliseconds.
License
Licensed under MIT or Apache-2.0; see MIT and Apache-2.0.
Contributing
Issues and Pull Requests are welcome! Please ensure:
- Code passes all tests
- Add appropriate documentation
- Follow the project's code style
Related Projects
- axum-otel - OpenTelemetry middleware for Axum Web framework
- OpenTelemetry Rust - OpenTelemetry Rust implementation
- tracing - Structured logging framework for Rust