1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4mod 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
47pub type Result<T> = std::result::Result<T, OpenTelemetryError>;
49
50#[derive(Debug, thiserror::Error)]
52pub enum OpenTelemetryError {
53 #[error("invalid OpenTelemetry configuration: {0}")]
55 Configuration(String),
56 #[error("failed to build OTLP exporter: {0}")]
58 Exporter(#[from] opentelemetry_otlp::ExporterBuildError),
59 #[error("OpenTelemetry SDK operation failed: {0}")]
61 Sdk(#[from] opentelemetry_sdk::error::OTelSdkError),
62 #[error("OpenTelemetry lifecycle task failed: {0}")]
64 TaskJoin(String),
65}
66
67#[derive(Clone, Copy, Debug, Eq, PartialEq)]
69pub enum OtlpProtocol {
70 Grpc,
72 HttpProtobuf,
74}
75
76#[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 pub fn grpc(service_name: impl Into<String>, endpoint: impl Into<String>) -> Self {
96 Self::new(service_name, endpoint, OtlpProtocol::Grpc)
97 }
98
99 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 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 pub fn with_service_version(mut self, version: impl Into<String>) -> Self {
152 self.service_version = Some(version.into());
153 self
154 }
155
156 pub fn with_environment(mut self, environment: impl Into<String>) -> Self {
158 self.environment = Some(environment.into());
159 self
160 }
161
162 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 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 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 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 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 pub fn service_name(&self) -> &str {
251 &self.service_name
252 }
253
254 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#[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 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 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 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 pub const fn provider(&self) -> &SdkTracerProvider {
407 &self.provider
408 }
409
410 pub const fn tracer(&self) -> &SdkTracer {
412 &self.tracer
413 }
414
415 pub fn register(&self, container: &mut Container) -> nidus_core::Result<()> {
417 container.register_singleton(self.clone())
418 }
419
420 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 pub fn extract_context(&self, headers: &HeaderMap) -> Context {
429 self.propagator.extract(&HeaderExtractor(headers))
430 }
431
432 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 pub fn install_global_propagator(&self) {
446 opentelemetry::global::set_text_map_propagator(composite_propagator());
447 }
448
449 pub fn is_ready(&self) -> bool {
451 !self.shutdown.load(Ordering::Acquire)
452 }
453
454 #[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 #[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 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 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}