Skip to main content

nidus_opentelemetry/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4//! Production OpenTelemetry tracing for Nidus.
5//!
6//! The pipeline uses the official SDK, a bounded batch processor, the
7//! `tracing` bridge, W3C Trace Context and baggage propagation, and either an
8//! OTLP gRPC or OTLP/HTTP protobuf exporter. It does not install a process-
9//! global tracing subscriber, so tests and applications retain lifecycle
10//! control.
11
12mod runtime_exporter;
13
14use std::{
15    collections::{BTreeMap, HashMap},
16    fmt,
17    sync::{
18        Arc,
19        atomic::{AtomicBool, Ordering},
20    },
21    time::Duration,
22};
23
24use async_trait::async_trait;
25use http::{HeaderMap, HeaderName, HeaderValue};
26use nidus_core::{Container, LifecycleHook, NidusError};
27use opentelemetry::{
28    Context, KeyValue,
29    propagation::{Extractor, Injector, TextMapCompositePropagator, TextMapPropagator},
30    trace::TracerProvider as _,
31};
32use opentelemetry_otlp::{WithExportConfig, WithHttpConfig, WithTonicConfig};
33use opentelemetry_sdk::{
34    Resource,
35    propagation::{BaggagePropagator, TraceContextPropagator},
36    trace::{
37        BatchConfigBuilder, BatchSpanProcessor, Sampler, SdkTracer, SdkTracerProvider, SpanExporter,
38    },
39};
40use tracing_opentelemetry::OpenTelemetrySpanExt;
41use tracing_subscriber::registry::LookupSpan;
42
43const MAX_HEADER_COUNT: usize = 32;
44const MAX_HEADER_BYTES: usize = 8 * 1024;
45const MAX_QUEUE_SIZE: usize = 65_536;
46
47/// Result type for OpenTelemetry pipeline operations.
48pub type Result<T> = std::result::Result<T, OpenTelemetryError>;
49
50/// Error returned while validating, starting, flushing, or stopping telemetry.
51#[derive(Debug, thiserror::Error)]
52pub enum OpenTelemetryError {
53    /// Configuration is unsafe or internally inconsistent.
54    #[error("invalid OpenTelemetry configuration: {0}")]
55    Configuration(String),
56    /// The OTLP exporter could not be built.
57    #[error("failed to build OTLP exporter: {0}")]
58    Exporter(#[from] opentelemetry_otlp::ExporterBuildError),
59    /// The SDK failed to flush or shut down.
60    #[error("OpenTelemetry SDK operation failed: {0}")]
61    Sdk(#[from] opentelemetry_sdk::error::OTelSdkError),
62    /// A blocking SDK lifecycle task failed to join.
63    #[error("OpenTelemetry lifecycle task failed: {0}")]
64    TaskJoin(String),
65}
66
67/// OTLP trace transport.
68#[derive(Clone, Copy, Debug, Eq, PartialEq)]
69pub enum OtlpProtocol {
70    /// OTLP over gRPC using Tonic.
71    Grpc,
72    /// OTLP over HTTP with protobuf payloads.
73    HttpProtobuf,
74}
75
76/// Redaction-safe, bounded OTLP pipeline configuration.
77#[derive(Clone)]
78pub struct OpenTelemetryConfig {
79    service_name: String,
80    service_version: Option<String>,
81    environment: Option<String>,
82    endpoint: String,
83    protocol: OtlpProtocol,
84    headers: BTreeMap<String, String>,
85    timeout: Duration,
86    queue_size: usize,
87    batch_size: usize,
88    scheduled_delay: Duration,
89    sample_ratio: f64,
90    allow_insecure_local_endpoint: bool,
91}
92
93impl OpenTelemetryConfig {
94    /// Creates a secure OTLP/gRPC configuration.
95    pub fn grpc(service_name: impl Into<String>, endpoint: impl Into<String>) -> Self {
96        Self::new(service_name, endpoint, OtlpProtocol::Grpc)
97    }
98
99    /// Creates a secure OTLP/HTTP protobuf configuration.
100    pub fn http_protobuf(service_name: impl Into<String>, endpoint: impl Into<String>) -> Self {
101        Self::new(service_name, endpoint, OtlpProtocol::HttpProtobuf)
102    }
103
104    /// Loads endpoint and protocol from standard OTLP environment variables.
105    ///
106    /// The endpoint must be explicit so production never silently falls back to
107    /// the upstream plaintext localhost default.
108    pub fn from_env(service_name: impl Into<String>) -> Result<Self> {
109        let endpoint = std::env::var("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
110            .or_else(|_| std::env::var("OTEL_EXPORTER_OTLP_ENDPOINT"))
111            .map_err(|_| {
112                OpenTelemetryError::Configuration(
113                    "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT is required"
114                        .to_owned(),
115                )
116            })?;
117        let protocol = std::env::var("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL")
118            .or_else(|_| std::env::var("OTEL_EXPORTER_OTLP_PROTOCOL"))
119            .unwrap_or_else(|_| "grpc".to_owned());
120        match protocol.as_str() {
121            "grpc" => Ok(Self::grpc(service_name, endpoint)),
122            "http/protobuf" => Ok(Self::http_protobuf(service_name, endpoint)),
123            _ => Err(OpenTelemetryError::Configuration(
124                "OTLP protocol must be grpc or http/protobuf".to_owned(),
125            )),
126        }
127    }
128
129    fn new(
130        service_name: impl Into<String>,
131        endpoint: impl Into<String>,
132        protocol: OtlpProtocol,
133    ) -> Self {
134        Self {
135            service_name: service_name.into(),
136            service_version: None,
137            environment: None,
138            endpoint: endpoint.into(),
139            protocol,
140            headers: BTreeMap::new(),
141            timeout: Duration::from_secs(10),
142            queue_size: 2_048,
143            batch_size: 512,
144            scheduled_delay: Duration::from_secs(5),
145            sample_ratio: 1.0,
146            allow_insecure_local_endpoint: false,
147        }
148    }
149
150    /// Sets the service version resource attribute.
151    pub fn with_service_version(mut self, version: impl Into<String>) -> Self {
152        self.service_version = Some(version.into());
153        self
154    }
155
156    /// Sets the deployment environment resource attribute.
157    pub fn with_environment(mut self, environment: impl Into<String>) -> Self {
158        self.environment = Some(environment.into());
159        self
160    }
161
162    /// Adds a bounded exporter header, such as an authorization token.
163    ///
164    /// Values are intentionally omitted from `Debug` output.
165    pub fn with_header(
166        mut self,
167        name: impl Into<String>,
168        value: impl Into<String>,
169    ) -> Result<Self> {
170        let name = name.into().to_ascii_lowercase();
171        let value = value.into();
172        HeaderName::from_bytes(name.as_bytes()).map_err(|_| {
173            OpenTelemetryError::Configuration("invalid OTLP header name".to_owned())
174        })?;
175        HeaderValue::from_str(&value).map_err(|_| {
176            OpenTelemetryError::Configuration("invalid OTLP header value".to_owned())
177        })?;
178        if value.len() > MAX_HEADER_BYTES {
179            return Err(OpenTelemetryError::Configuration(
180                "OTLP header value exceeds 8192 bytes".to_owned(),
181            ));
182        }
183        if !self.headers.contains_key(&name) && self.headers.len() == MAX_HEADER_COUNT {
184            return Err(OpenTelemetryError::Configuration(
185                "OTLP header count exceeds 32".to_owned(),
186            ));
187        }
188        self.headers.insert(name, value);
189        Ok(self)
190    }
191
192    /// Sets exporter request timeout.
193    pub fn with_timeout(mut self, timeout: Duration) -> Result<Self> {
194        if timeout.is_zero() || timeout > Duration::from_secs(120) {
195            return Err(OpenTelemetryError::Configuration(
196                "OTLP timeout must be between 1 millisecond and 120 seconds".to_owned(),
197            ));
198        }
199        self.timeout = timeout;
200        Ok(self)
201    }
202
203    /// Sets bounded batch processor parameters.
204    pub fn with_batching(
205        mut self,
206        queue_size: usize,
207        batch_size: usize,
208        scheduled_delay: Duration,
209    ) -> Result<Self> {
210        if queue_size == 0
211            || queue_size > MAX_QUEUE_SIZE
212            || batch_size == 0
213            || batch_size > queue_size
214            || scheduled_delay.is_zero()
215            || scheduled_delay > Duration::from_secs(60)
216        {
217            return Err(OpenTelemetryError::Configuration(
218                "OTLP batching requires 1 <= batch <= queue <= 65536 and delay <= 60s".to_owned(),
219            ));
220        }
221        self.queue_size = queue_size;
222        self.batch_size = batch_size;
223        self.scheduled_delay = scheduled_delay;
224        Ok(self)
225    }
226
227    /// Sets parent-based trace ID ratio sampling.
228    pub fn with_sample_ratio(mut self, ratio: f64) -> Result<Self> {
229        if !ratio.is_finite() || !(0.0..=1.0).contains(&ratio) {
230            return Err(OpenTelemetryError::Configuration(
231                "trace sample ratio must be between 0 and 1".to_owned(),
232            ));
233        }
234        self.sample_ratio = ratio;
235        Ok(self)
236    }
237
238    /// Allows plaintext only for an explicit loopback collector endpoint.
239    pub fn allow_insecure_local_endpoint(mut self) -> Result<Self> {
240        if !is_loopback_endpoint(&self.endpoint) {
241            return Err(OpenTelemetryError::Configuration(
242                "insecure OTLP endpoints are restricted to loopback".to_owned(),
243            ));
244        }
245        self.allow_insecure_local_endpoint = true;
246        Ok(self)
247    }
248
249    /// Returns the stable service name.
250    pub fn service_name(&self) -> &str {
251        &self.service_name
252    }
253
254    /// Returns the selected exporter protocol.
255    pub const fn protocol(&self) -> OtlpProtocol {
256        self.protocol
257    }
258
259    fn validate(&self) -> Result<()> {
260        if self.service_name.is_empty() || self.service_name.len() > 255 {
261            return Err(OpenTelemetryError::Configuration(
262                "service name must contain 1..=255 bytes".to_owned(),
263            ));
264        }
265        let uri: http::Uri = self.endpoint.parse().map_err(|_| {
266            OpenTelemetryError::Configuration("OTLP endpoint is not a valid URI".to_owned())
267        })?;
268        let scheme = uri.scheme_str().unwrap_or_default();
269        if scheme != "https"
270            && !(scheme == "http"
271                && self.allow_insecure_local_endpoint
272                && is_loopback_endpoint(&self.endpoint))
273        {
274            return Err(OpenTelemetryError::Configuration(
275                "OTLP endpoint must use HTTPS unless loopback plaintext is explicitly enabled"
276                    .to_owned(),
277            ));
278        }
279        Ok(())
280    }
281}
282
283impl fmt::Debug for OpenTelemetryConfig {
284    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
285        formatter
286            .debug_struct("OpenTelemetryConfig")
287            .field("service_name", &self.service_name)
288            .field("service_version", &self.service_version)
289            .field("environment", &self.environment)
290            .field("endpoint", &"<redacted>")
291            .field("protocol", &self.protocol)
292            .field("header_names", &self.headers.keys().collect::<Vec<_>>())
293            .field("timeout", &self.timeout)
294            .field("queue_size", &self.queue_size)
295            .field("batch_size", &self.batch_size)
296            .field("scheduled_delay", &self.scheduled_delay)
297            .field("sample_ratio", &self.sample_ratio)
298            .field(
299                "allow_insecure_local_endpoint",
300                &self.allow_insecure_local_endpoint,
301            )
302            .finish()
303    }
304}
305
306/// Owned SDK provider, tracing bridge factory, and W3C propagator.
307#[derive(Clone)]
308pub struct OpenTelemetryPipeline {
309    provider: SdkTracerProvider,
310    tracer: SdkTracer,
311    propagator: Arc<TextMapCompositePropagator>,
312    shutdown: Arc<AtomicBool>,
313    shutdown_timeout: Duration,
314}
315
316impl OpenTelemetryPipeline {
317    /// Builds a real OTLP exporter and bounded SDK batch pipeline.
318    /// Create within Tokio and keep that runtime alive through shutdown: async
319    /// exporters use its reactor when polled on the SDK's dedicated batch thread.
320    pub fn init(config: OpenTelemetryConfig) -> Result<Self> {
321        config.validate()?;
322        let exporter = match config.protocol {
323            OtlpProtocol::Grpc => {
324                let metadata = tonic_metadata(&config.headers)?;
325                opentelemetry_otlp::SpanExporter::builder()
326                    .with_tonic()
327                    .with_endpoint(config.endpoint.clone())
328                    .with_timeout(config.timeout)
329                    .with_metadata(metadata)
330                    .build()?
331            }
332            OtlpProtocol::HttpProtobuf => opentelemetry_otlp::SpanExporter::builder()
333                .with_http()
334                .with_endpoint(config.endpoint.clone())
335                .with_timeout(config.timeout)
336                .with_headers(
337                    config
338                        .headers
339                        .clone()
340                        .into_iter()
341                        .collect::<HashMap<_, _>>(),
342                )
343                .build()?,
344        };
345        Self::from_exporter(config, exporter)
346    }
347
348    /// Builds the same SDK pipeline around a custom exporter.
349    ///
350    /// This is useful for first-party tests and private exporters while keeping
351    /// batching, resources, sampling, propagation, and shutdown identical.
352    pub fn from_exporter<E>(config: OpenTelemetryConfig, exporter: E) -> Result<Self>
353    where
354        E: SpanExporter + 'static,
355    {
356        config.validate()?;
357        let mut attributes = Vec::new();
358        if let Some(version) = &config.service_version {
359            attributes.push(KeyValue::new("service.version", version.clone()));
360        }
361        if let Some(environment) = &config.environment {
362            attributes.push(KeyValue::new(
363                "deployment.environment.name",
364                environment.clone(),
365            ));
366        }
367        let resource = Resource::builder()
368            .with_service_name(config.service_name.clone())
369            .with_attributes(attributes)
370            .build();
371        let batch = BatchSpanProcessor::builder(runtime_exporter::RuntimeExporter::new(exporter))
372            .with_batch_config(
373                BatchConfigBuilder::default()
374                    .with_max_queue_size(config.queue_size)
375                    .with_max_export_batch_size(config.batch_size)
376                    .with_scheduled_delay(config.scheduled_delay)
377                    .build(),
378            )
379            .build();
380        let provider = SdkTracerProvider::builder()
381            .with_span_processor(batch)
382            .with_sampler(Sampler::ParentBased(Box::new(Sampler::TraceIdRatioBased(
383                config.sample_ratio,
384            ))))
385            .with_resource(resource)
386            .build();
387        let tracer = provider.tracer(config.service_name);
388        Ok(Self {
389            provider,
390            tracer,
391            propagator: Arc::new(composite_propagator()),
392            shutdown: Arc::new(AtomicBool::new(false)),
393            shutdown_timeout: config.timeout,
394        })
395    }
396
397    /// Returns a `tracing_subscriber` layer backed by this SDK provider.
398    pub fn tracing_layer<S>(&self) -> tracing_opentelemetry::OpenTelemetryLayer<S, SdkTracer>
399    where
400        S: tracing::Subscriber + for<'span> LookupSpan<'span>,
401    {
402        tracing_opentelemetry::layer().with_tracer(self.tracer.clone())
403    }
404
405    /// Returns the native SDK tracer provider.
406    pub const fn provider(&self) -> &SdkTracerProvider {
407        &self.provider
408    }
409
410    /// Returns the native SDK tracer.
411    pub const fn tracer(&self) -> &SdkTracer {
412        &self.tracer
413    }
414
415    /// Registers this pipeline as a typed singleton dependency.
416    pub fn register(&self, container: &mut Container) -> nidus_core::Result<()> {
417        container.register_singleton(self.clone())
418    }
419
420    /// Injects the current `tracing` span into HTTP headers using W3C formats.
421    pub fn inject_current_context(&self, headers: &mut HeaderMap) {
422        let context = tracing::Span::current().context();
423        self.propagator
424            .inject_context(&context, &mut HeaderInjector(headers));
425    }
426
427    /// Extracts W3C trace context and baggage from HTTP headers.
428    pub fn extract_context(&self, headers: &HeaderMap) -> Context {
429        self.propagator.extract(&HeaderExtractor(headers))
430    }
431
432    /// Sets a tracing span's remote parent from HTTP headers.
433    pub fn set_parent_from_headers(
434        &self,
435        span: &tracing::Span,
436        headers: &HeaderMap,
437    ) -> std::result::Result<(), tracing_opentelemetry::SetParentError> {
438        span.set_parent(self.extract_context(headers))
439    }
440
441    /// Installs W3C trace context and baggage as the process-global propagator.
442    ///
443    /// Most Nidus applications should prefer the scoped header methods. Global
444    /// installation is explicit because OpenTelemetry has no restoration guard.
445    pub fn install_global_propagator(&self) {
446        opentelemetry::global::set_text_map_propagator(composite_propagator());
447    }
448
449    /// Returns whether the provider remains available for export.
450    pub fn is_ready(&self) -> bool {
451        !self.shutdown.load(Ordering::Acquire)
452    }
453
454    /// Adds SDK lifecycle state as a Nidus readiness check.
455    #[cfg(feature = "health")]
456    pub fn register_ready_check(
457        self: Arc<Self>,
458        registry: nidus_http::health::HealthRegistry,
459        name: impl Into<String>,
460    ) -> nidus_http::health::HealthRegistry {
461        registry.ready_check(name, move || {
462            let pipeline = Arc::clone(&self);
463            async move {
464                if pipeline.is_ready() {
465                    nidus_http::health::HealthStatus::up()
466                } else {
467                    nidus_http::health::HealthStatus::down("OpenTelemetry pipeline has shut down")
468                }
469            }
470        })
471    }
472
473    /// Records redaction-safe SDK readiness in the Nidus dashboard timeline.
474    #[cfg(feature = "dashboard")]
475    pub async fn record_dashboard_status(
476        &self,
477        collector: &nidus_dashboard::DashboardCollector<
478            nidus_dashboard::storage::DashboardStorageHandle,
479        >,
480    ) -> nidus_dashboard::Result<()> {
481        collector
482            .record_adapter("nidus-opentelemetry.readiness", None, self.is_ready(), 0)
483            .await
484    }
485
486    /// Flushes all currently queued spans off the async runtime worker.
487    pub async fn force_flush(&self) -> Result<()> {
488        if !self.is_ready() {
489            return Err(OpenTelemetryError::Sdk(
490                opentelemetry_sdk::error::OTelSdkError::AlreadyShutdown,
491            ));
492        }
493        let provider = self.provider.clone();
494        tokio::task::spawn_blocking(move || provider.force_flush())
495            .await
496            .map_err(|error| OpenTelemetryError::TaskJoin(error.to_string()))??;
497        Ok(())
498    }
499
500    /// Flushes and stops the SDK batch processor exactly once.
501    pub async fn shutdown(&self) -> Result<()> {
502        if self
503            .shutdown
504            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
505            .is_err()
506        {
507            return Ok(());
508        }
509        let provider = self.provider.clone();
510        let timeout = self.shutdown_timeout;
511        tokio::task::spawn_blocking(move || provider.shutdown_with_timeout(timeout))
512            .await
513            .map_err(|error| OpenTelemetryError::TaskJoin(error.to_string()))??;
514        Ok(())
515    }
516}
517
518impl fmt::Debug for OpenTelemetryPipeline {
519    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
520        formatter
521            .debug_struct("OpenTelemetryPipeline")
522            .field("ready", &self.is_ready())
523            .field("shutdown_timeout", &self.shutdown_timeout)
524            .finish_non_exhaustive()
525    }
526}
527
528#[async_trait]
529impl LifecycleHook for OpenTelemetryPipeline {
530    async fn on_shutdown(&self) -> nidus_core::Result<()> {
531        self.shutdown()
532            .await
533            .map_err(|_| NidusError::ApplicationBuild {
534                message: "OpenTelemetry flush failed during shutdown".to_owned(),
535            })
536    }
537}
538
539struct HeaderInjector<'a>(&'a mut HeaderMap);
540
541impl Injector for HeaderInjector<'_> {
542    fn set(&mut self, key: &str, value: String) {
543        let Ok(name) = HeaderName::from_bytes(key.as_bytes()) else {
544            return;
545        };
546        let Ok(value) = HeaderValue::from_str(&value) else {
547            return;
548        };
549        self.0.insert(name, value);
550    }
551}
552
553struct HeaderExtractor<'a>(&'a HeaderMap);
554
555impl Extractor for HeaderExtractor<'_> {
556    fn get(&self, key: &str) -> Option<&str> {
557        self.0.get(key).and_then(|value| value.to_str().ok())
558    }
559
560    fn keys(&self) -> Vec<&str> {
561        self.0.keys().map(HeaderName::as_str).collect()
562    }
563}
564
565fn composite_propagator() -> TextMapCompositePropagator {
566    TextMapCompositePropagator::new(vec![
567        Box::new(TraceContextPropagator::new()),
568        Box::new(BaggagePropagator::new()),
569    ])
570}
571
572fn tonic_metadata(headers: &BTreeMap<String, String>) -> Result<tonic::metadata::MetadataMap> {
573    let mut metadata = tonic::metadata::MetadataMap::new();
574    for (name, value) in headers {
575        let key = tonic::metadata::MetadataKey::from_bytes(name.as_bytes()).map_err(|_| {
576            OpenTelemetryError::Configuration("invalid gRPC metadata name".to_owned())
577        })?;
578        let value = tonic::metadata::MetadataValue::try_from(value.as_str()).map_err(|_| {
579            OpenTelemetryError::Configuration("invalid gRPC metadata value".to_owned())
580        })?;
581        metadata.insert(key, value);
582    }
583    Ok(metadata)
584}
585
586fn is_loopback_endpoint(endpoint: &str) -> bool {
587    url::Url::parse(endpoint).ok().is_some_and(|url| {
588        url.scheme() == "http"
589            && match url.host() {
590                Some(url::Host::Domain(host)) => host.eq_ignore_ascii_case("localhost"),
591                Some(url::Host::Ipv4(host)) => host.is_loopback(),
592                Some(url::Host::Ipv6(host)) => host.is_loopback(),
593                None => false,
594            }
595    })
596}