Module telemetry 

Telemetry Module - Educational Implementation

This module provides production-grade OpenTelemetry integration for a tiny CLI tool. This is intentionally over-engineered for educational purposes!

Why This Exists

A simple cron parser doesn’t “need” distributed tracing. However, this demonstrates:

1. How to add observability to any Rust CLI
2. OpenTelemetry patterns that scale from tiny tools to large systems
3. Handling async/gRPC in short-lived processes

Key Features

• Optional at runtime: Zero overhead if OTEL_EXPORTER_OTLP_ENDPOINT not set
• Multi-backend support: Jaeger, Honeycomb, Grafana Tempo, AWS X-Ray, etc.
• Secure: TLS, header authentication, compression
• Production-ready: Proper resource attributes, propagation, graceful shutdown

Known Limitation: Short-lived Process Challenge

Short-lived CLIs exit faster than spans can flush:

• CLI execution: ~10ms
• Span flush timeout: 5000ms
• Result: You may see “BatchSpanProcessor.Shutdown.Timeout”

This is expected and cosmetic - spans are still sent asynchronously!

To suppress: export RUST_LOG="warn,opentelemetry_sdk=error"

Usage in Your Own Projects

1. Copy this module
2. Add #[instrument] to functions you want to trace
3. Call telemetry::init() at startup
4. Call telemetry::shutdown_tracer() before exit
5. Set OTEL_EXPORTER_OTLP_ENDPOINT when you want tracing

Dependencies Required

opentelemetry = "0.31.0"
opentelemetry-otlp = { version = "0.31.0", features = ["grpc-tonic", "tls"] }
opentelemetry_sdk = { version = "0.31.0", features = ["rt-tokio"] }
tokio = { version = "1", features = ["rt", "macros"] }
tracing = "0.1"
tracing-opentelemetry = "0.32.0"
tracing-subscriber = "0.3"

Functions

init

Initialize logging + (optional) tracing exporter Tracing is enabled if OTEL_EXPORTER_OTLP_ENDPOINT is set (gRPC only).

shutdown_tracer

Gracefully shut down tracer provider (noop if not initialized)