apollo_opentelemetry/

telemetry.rs

//! Core telemetry management.
//!
//! This module provides the [`Telemetry`] struct for unified management of
//! OpenTelemetry traces, metrics, and logs providers.
//!
//! # Getting Started
//!
//! Use [`Telemetry::builder()`] to create a telemetry instance with custom
//! configuration, or [`Telemetry::new()`] for configuration-only setup.
//!
//! # Example
//!
//! ```no_run
//! use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Create from configuration
//! let telemetry = Telemetry::new(OpenTelemetryConfig::default())?;
//!
//! // Or use builder for custom setup with all global registrations
//! let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
//!     .with_globals()
//!     .build()?;
//! # Ok(())
//! # }
//! ```

use opentelemetry::global;
use opentelemetry_appender_log::OpenTelemetryLogBridge;
use opentelemetry_sdk::Resource;
use opentelemetry_sdk::logs::{LoggerProviderBuilder, SdkLoggerProvider};
use opentelemetry_sdk::metrics::{Instrument, MeterProviderBuilder, SdkMeterProvider, Stream};
use opentelemetry_sdk::trace::{
    SdkTracerProvider, SpanExporter, SpanProcessor, TracerProviderBuilder,
};
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

use crate::config::OpenTelemetryConfig;
use crate::{InitError, providers};
use tokio::runtime::RuntimeFlavor;

/// Builder for configuring and creating a [`Telemetry`] instance.
///
/// Use this builder to combine configuration-based setup with programmatic
/// customization. Exporters and processors added via the builder are used
/// in addition to those specified in the configuration.
///
/// You can register telemetry providers globally using:
/// - [`with_global_tracer_provider()`](TelemetryBuilder::with_global_tracer_provider)
/// - [`with_global_meter_provider()`](TelemetryBuilder::with_global_meter_provider)
/// - [`with_log_bridge()`](TelemetryBuilder::with_log_bridge)
/// - [`with_tracing_bridge()`](TelemetryBuilder::with_tracing_bridge)
/// - [`with_global_propagator()`](TelemetryBuilder::with_global_propagator)
///
/// Or use [`with_globals()`](TelemetryBuilder::with_globals) to enable all of them at once.
///
/// # Example
///
/// ```no_run
/// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let config = OpenTelemetryConfig::default();
/// let telemetry = Telemetry::builder(config).with_globals().build()?;
/// # Ok(())
/// # }
/// ```
pub struct TelemetryBuilder {
    config: OpenTelemetryConfig,
    set_global_tracer: bool,
    set_global_meter: bool,
    set_global_propagator: bool,
    enable_log_bridge: bool,
    enable_tracing_bridge: bool,
    resource_builder: Option<opentelemetry_sdk::resource::ResourceBuilder>,
    tracer_builder: Option<TracerProviderBuilder>,
    meter_builder: Option<MeterProviderBuilder>,
    logger_builder: Option<LoggerProviderBuilder>,
}

impl TelemetryBuilder {
    /// Create a new builder with the given configuration.
    ///
    /// By default, nothing is registered globally. Use [`with_globals()`](Self::with_globals)
    /// to opt in to all global registrations, or individual methods to opt in selectively.
    pub fn new(config: OpenTelemetryConfig) -> Self {
        Self {
            config,
            set_global_tracer: false,
            set_global_meter: false,
            set_global_propagator: false,
            enable_log_bridge: false,
            enable_tracing_bridge: false,
            resource_builder: None,
            tracer_builder: None,
            meter_builder: None,
            logger_builder: None,
        }
    }

    fn tracer_builder(&mut self) -> TracerProviderBuilder {
        self.tracer_builder
            .take()
            .unwrap_or_else(SdkTracerProvider::builder)
    }

    fn meter_builder(&mut self) -> MeterProviderBuilder {
        self.meter_builder
            .take()
            .unwrap_or_else(SdkMeterProvider::builder)
    }

    fn logger_builder(&mut self) -> LoggerProviderBuilder {
        self.logger_builder
            .take()
            .unwrap_or_else(SdkLoggerProvider::builder)
    }

    /// Register the tracer provider as the global tracer provider.
    ///
    /// When enabled, you can use `opentelemetry::global::tracer()` to obtain
    /// tracers anywhere in your application.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry::global;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_global_tracer_provider()
    ///     .build()?;
    ///
    /// // Now you can get tracers from anywhere
    /// let tracer = global::tracer("my-component");
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_global_tracer_provider(mut self) -> Self {
        self.set_global_tracer = true;
        self
    }

    /// Register the meter provider as the global meter provider.
    ///
    /// When enabled, you can use `opentelemetry::global::meter()` to obtain
    /// meters anywhere in your application.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry::global;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_global_meter_provider()
    ///     .build()?;
    ///
    /// // Now you can get meters from anywhere
    /// let meter = global::meter("my-component");
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_global_meter_provider(mut self) -> Self {
        self.set_global_meter = true;
        self
    }

    /// Register the propagator configuration as the global text map propagator.
    ///
    /// When enabled, tower middleware such as `http_server_propagation()` and
    /// `http_client_propagation()` automatically use the configured propagator.
    pub fn with_global_propagator(mut self) -> Self {
        self.set_global_propagator = true;
        self
    }

    /// Enable all global registrations at once.
    ///
    /// Equivalent to calling [`with_global_tracer_provider()`](Self::with_global_tracer_provider),
    /// [`with_global_meter_provider()`](Self::with_global_meter_provider),
    /// [`with_log_bridge()`](Self::with_log_bridge),
    /// [`with_tracing_bridge()`](Self::with_tracing_bridge), and
    /// [`with_global_propagator()`](Self::with_global_propagator).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_globals()
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_globals(self) -> Self {
        self.with_global_tracer_provider()
            .with_global_meter_provider()
            .with_log_bridge()
            .with_tracing_bridge()
            .with_global_propagator()
    }

    /// Enable the log bridge to route `log` crate macros to OpenTelemetry.
    ///
    /// When enabled, calls to `log::info!()`, `log::error!()`, etc. will be
    /// exported as OpenTelemetry log records through the configured logger provider.
    ///
    /// The bridge respects the `RUST_LOG` environment variable for filtering.
    /// If `RUST_LOG` is not set, defaults to `info` level.
    ///
    /// **Note**: This sets the global logger, so it can only be called once per process.
    /// Calling `build()` will fail if another logger is already installed.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_log_bridge()
    ///     .build()?;
    ///
    /// // Now log macros are routed to OpenTelemetry
    /// log::info!("This goes to OpenTelemetry");
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_log_bridge(mut self) -> Self {
        self.enable_log_bridge = true;
        self
    }

    /// Enable the tracing bridge to route `tracing` crate spans and events to OpenTelemetry.
    ///
    /// When enabled, `tracing::info!()`, `tracing::span!()`, etc. will be exported
    /// as OpenTelemetry log records and traces through the configured providers.
    ///
    /// The bridge respects the `RUST_LOG` environment variable for filtering.
    /// If `RUST_LOG` is not set, defaults to `info` level.
    ///
    /// **Note**: This sets the global tracing subscriber, so it can only be called once
    /// per process. Calling `build()` will fail if another subscriber is already installed.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    ///
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::logs_to_stderr())
    ///     .with_tracing_bridge()
    ///     .build()?;
    ///
    /// // Now tracing macros are routed to OpenTelemetry
    /// tracing::info!("This goes to OpenTelemetry");
    /// ```
    pub fn with_tracing_bridge(mut self) -> Self {
        self.enable_tracing_bridge = true;
        self
    }

    // --- Resource configuration ---

    /// Set the resource builder for configuring resource attributes.
    ///
    /// Resource attributes provide identifying information about the entity
    /// producing telemetry (e.g., service name, version, deployment environment).
    ///
    /// Attributes from the builder are merged with any resource configuration
    /// from the config file. On conflicts, builder values take precedence,
    /// allowing you to override specific attributes like `service.name` while
    /// keeping other config-defined attributes.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry_sdk::Resource;
    /// use opentelemetry::KeyValue;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_resource_builder(
    ///         Resource::builder()
    ///             .with_service_name("my-service")
    ///             .with_attributes([
    ///                 KeyValue::new("service.version", "1.0.0"),
    ///                 KeyValue::new("deployment.environment", "production"),
    ///             ])
    ///     )
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_resource_builder(
        mut self,
        builder: opentelemetry_sdk::resource::ResourceBuilder,
    ) -> Self {
        self.resource_builder = Some(builder);
        self
    }

    // --- Tracer configuration ---

    /// Add a custom span processor to the tracer provider.
    ///
    /// Span processors receive spans as they are started and ended, allowing
    /// for custom processing logic such as filtering, enrichment, or routing
    /// to multiple exporters.
    ///
    /// This is added in addition to any processors configured via the
    /// configuration file.
    pub fn with_span_processor<T: SpanProcessor + 'static>(mut self, processor: T) -> Self {
        self.tracer_builder = Some(self.tracer_builder().with_span_processor(processor));
        self
    }

    /// Add a span exporter with batch processing.
    ///
    /// Batch processing buffers spans and exports them in batches, which is
    /// more efficient for production use. This is the recommended approach
    /// for most applications.
    ///
    /// This is added in addition to any exporters configured via the
    /// configuration file.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry_otlp::SpanExporter;
    ///
    /// let exporter = SpanExporter::builder()
    ///     .with_http()
    ///     .with_endpoint("http://localhost:4318")
    ///     .build()
    ///     .unwrap();
    ///
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_batch_span_exporter(exporter)
    ///     .build()
    ///     .unwrap();
    /// ```
    pub fn with_batch_span_exporter<T: SpanExporter + 'static>(mut self, exporter: T) -> Self {
        self.tracer_builder = Some(self.tracer_builder().with_batch_exporter(exporter));
        self
    }

    /// Add a span exporter with simple (synchronous) processing.
    ///
    /// Simple processing exports spans immediately as they complete. This is
    /// useful for development and debugging but may impact performance in
    /// production.
    ///
    /// This is added in addition to any exporters configured via the
    /// configuration file.
    pub fn with_simple_span_exporter<T: SpanExporter + 'static>(mut self, exporter: T) -> Self {
        self.tracer_builder = Some(self.tracer_builder().with_simple_exporter(exporter));
        self
    }

    // --- Meter configuration ---

    /// Add a metric view for customizing metric aggregation.
    ///
    /// Views allow you to customize how metrics are collected and reported.
    /// The view function receives instrument metadata and can return a
    /// [`Stream`] configuration to modify the instrument's behavior.
    ///
    /// Return `Some(Stream)` to apply customizations, or `None` to use
    /// the default behavior.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry_sdk::metrics::{Instrument, Stream};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_view(|instrument: &Instrument| {
    ///         // Customize high-cardinality metrics
    ///         if instrument.name().contains("debug") {
    ///             Some(Stream::default())
    ///         } else {
    ///             None // Use default behavior
    ///         }
    ///     })
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn with_view<F>(mut self, view: F) -> Self
    where
        F: Fn(&Instrument) -> Option<Stream> + Send + Sync + 'static,
    {
        self.meter_builder = Some(self.meter_builder().with_view(view));
        self
    }

    /// Add a periodic reader for push-based metric export.
    ///
    /// A [`PeriodicReader`] collects metrics at regular intervals and pushes
    /// them to the configured exporter. Use [`PeriodicReaderBuilder`] for
    /// custom interval and timeout settings.
    ///
    /// This is added in addition to any readers configured via the
    /// configuration file.
    ///
    /// # Example
    ///
    /// ```ignore
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    /// use opentelemetry_sdk::metrics::PeriodicReader;
    /// use opentelemetry_otlp::MetricExporter;
    /// use std::time::Duration;
    ///
    /// let exporter = MetricExporter::builder().with_http().build()?;
    /// let reader = PeriodicReader::builder(exporter)
    ///     .with_interval(Duration::from_secs(30))
    ///     .build();
    ///
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_periodic_reader(reader)
    ///     .build()?;
    /// ```
    ///
    /// [`PeriodicReader`]: opentelemetry_sdk::metrics::PeriodicReader
    /// [`PeriodicReaderBuilder`]: opentelemetry_sdk::metrics::PeriodicReaderBuilder
    pub fn with_periodic_reader<E>(
        mut self,
        reader: opentelemetry_sdk::metrics::PeriodicReader<E>,
    ) -> Self
    where
        E: opentelemetry_sdk::metrics::exporter::PushMetricExporter,
    {
        self.meter_builder = Some(self.meter_builder().with_reader(reader));
        self
    }

    // --- Logger configuration ---

    /// Add a log exporter with batch processing.
    ///
    /// Batch processing buffers log records and exports them in batches,
    /// which is more efficient for production use.
    ///
    /// This is added in addition to any exporters configured via the
    /// configuration file.
    pub fn with_batch_log_exporter<T>(mut self, exporter: T) -> Self
    where
        T: opentelemetry_sdk::logs::LogExporter + 'static,
    {
        self.logger_builder = Some(self.logger_builder().with_batch_exporter(exporter));
        self
    }

    /// Add a log exporter with simple (synchronous) processing.
    ///
    /// Simple processing exports log records immediately. This is useful
    /// for development and debugging but may impact performance in production.
    ///
    /// This is added in addition to any exporters configured via the
    /// configuration file.
    pub fn with_simple_log_exporter<T>(mut self, exporter: T) -> Self
    where
        T: opentelemetry_sdk::logs::LogExporter + 'static,
    {
        self.logger_builder = Some(self.logger_builder().with_simple_exporter(exporter));
        self
    }

    /// Build the [`Telemetry`] instance.
    ///
    /// This initializes the OpenTelemetry providers based on the configuration
    /// and any programmatic customizations. Providers are only created if
    /// they are configured or have programmatic additions.
    ///
    /// # Errors
    ///
    /// Returns an error if exporter initialization fails (e.g., invalid
    /// endpoint, missing credentials, or required feature not enabled).
    pub fn build(self) -> Result<Telemetry, InitError> {
        // If disabled, return empty telemetry
        if self.config.disabled == Some(true) {
            return Ok(Telemetry {
                tracer_provider: None,
                meter_provider: None,
                logger_provider: None,
            });
        }

        // Build resource: start with config, then add builder values (builder wins on conflicts)
        let config_resource: Resource = (&self.config.resource).into();
        let resource = match self.resource_builder {
            Some(builder) => {
                // Start with an empty builder, add config attrs, then builder attrs (last wins)
                let config_attrs: Vec<_> = config_resource
                    .iter()
                    .map(|(k, v)| opentelemetry::KeyValue::new(k.clone(), v.clone()))
                    .collect();
                Resource::builder_empty()
                    .with_attributes(config_attrs)
                    .with_attributes(
                        builder
                            .build()
                            .iter()
                            .map(|(k, v)| opentelemetry::KeyValue::new(k.clone(), v.clone())),
                    )
                    .build()
            }
            None => config_resource,
        };

        // Build tracer provider
        let builder = self
            .tracer_builder
            .unwrap_or_else(SdkTracerProvider::builder);
        let tracer_provider =
            providers::traces::build_tracer_provider(&self.config, resource.clone(), builder)?;

        // Build meter provider
        let builder = self.meter_builder.unwrap_or_else(SdkMeterProvider::builder);
        let meter_provider =
            providers::metrics::build_meter_provider(&self.config, resource.clone(), builder)?;

        // Build logger provider
        let builder = self
            .logger_builder
            .unwrap_or_else(SdkLoggerProvider::builder);
        let logger_provider =
            providers::logs::build_logger_provider(&self.config, resource, builder)?;

        // In tests we do not set the global providers to avoid polluting the global state
        #[cfg(not(test))]
        {
            // Set global providers if requested and track ownership
            if self.set_global_tracer {
                global::set_tracer_provider(tracer_provider.clone());
            }

            if self.set_global_meter {
                global::set_meter_provider(meter_provider.clone());
            }

            if self.set_global_propagator {
                global::set_text_map_propagator(
                    opentelemetry::propagation::TextMapCompositePropagator::from(
                        &self.config.propagator,
                    ),
                );
            }

            // Set up log bridge if requested
            if self.enable_log_bridge {
                setup_log_bridge(&logger_provider)?;
            }

            // Set up tracing bridge if requested
            if self.enable_tracing_bridge {
                setup_tracing_bridge(&logger_provider)?;
            }
        }

        Ok(Telemetry {
            tracer_provider: Some(tracer_provider),
            meter_provider: Some(meter_provider),
            logger_provider: Some(logger_provider),
        })
    }
}

/// Set up the log crate bridge to route logs to OpenTelemetry.
fn setup_log_bridge(logger_provider: &SdkLoggerProvider) -> Result<(), InitError> {
    let otel_log_bridge = OpenTelemetryLogBridge::new(logger_provider);

    // Build filter from RUST_LOG, defaulting to info level
    let mut builder = env_filter::Builder::new();
    builder.filter_level(log::LevelFilter::Info);
    // Filter out OTel internal logs to prevent infinite recursion
    builder.filter_module("opentelemetry", log::LevelFilter::Off);
    builder.filter_module("opentelemetry_sdk", log::LevelFilter::Off);
    if let Ok(rust_log) = std::env::var("RUST_LOG") {
        builder.parse(&rust_log);
    }
    let filter = builder.build();
    let max_level = filter.filter();

    let logger = env_filter::FilteredLog::new(otel_log_bridge, filter);
    log::set_logger(Box::leak(Box::new(logger))).map_err(|e| InitError::Bridge {
        bridge: "log".to_string(),
        reason: e.to_string(),
    })?;
    log::set_max_level(max_level);

    Ok(())
}

/// Set up the tracing crate bridge to route events to OpenTelemetry logs.
fn setup_tracing_bridge(logger_provider: &SdkLoggerProvider) -> Result<(), InitError> {
    let otel_layer =
        opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge::new(logger_provider);

    // Build filter from RUST_LOG, defaulting to info level
    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info"))
        // Filter out OTel internal logs to prevent infinite recursion
        .add_directive("opentelemetry=off".parse().unwrap())
        .add_directive("opentelemetry_sdk=off".parse().unwrap());

    tracing_subscriber::registry()
        .with(filter)
        .with(otel_layer)
        .try_init()
        .map_err(|e| InitError::Bridge {
            bridge: "tracing".to_string(),
            reason: e.to_string(),
        })?;

    Ok(())
}

/// Unified telemetry management for traces, metrics, and logs.
///
/// This struct holds the OpenTelemetry providers and ensures proper shutdown
/// when dropped. Create an instance at application startup and keep it alive
/// for the duration of your application.
///
/// # Lifecycle
///
/// - Create at application startup using [`Telemetry::new()`] or [`Telemetry::builder()`]
/// - Keep the instance alive (e.g., in your main function or as application state)
/// - Providers automatically shut down when `Telemetry` is dropped
/// - For explicit shutdown control, call [`Telemetry::shutdown()`]
///
/// # Example
///
/// ```no_run
/// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Initialize at startup
/// let telemetry = Telemetry::new(OpenTelemetryConfig::default())?;
///
/// // Access providers if needed
/// if let Some(tracer_provider) = telemetry.tracer_provider() {
///     // Use the tracer provider directly
/// }
///
/// // Telemetry shuts down automatically when dropped
/// # Ok(())
/// # }
/// ```
pub struct Telemetry {
    tracer_provider: Option<SdkTracerProvider>,
    meter_provider: Option<SdkMeterProvider>,
    logger_provider: Option<SdkLoggerProvider>,
}

impl Telemetry {
    /// Create a no-op telemetry instance with no providers or output.
    ///
    /// This returns a `Telemetry` instance that does nothing: no providers
    /// are created, no global providers are set, and no data is exported.
    /// This is useful for:
    ///
    /// - **Tests**: When you need a `Telemetry` instance but don't want actual
    ///   telemetry overhead or output.
    /// - **Disabled telemetry**: When you want to completely disable telemetry
    ///   without going through configuration parsing.
    pub fn none() -> Self {
        Self {
            tracer_provider: None,
            meter_provider: None,
            logger_provider: None,
        }
    }

    /// Create a builder for configuring telemetry.
    ///
    /// Use the builder when you need to add custom exporters, processors,
    /// or views programmatically.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let telemetry = Telemetry::builder(OpenTelemetryConfig::default())
    ///     .with_global_tracer_provider()
    ///     .build()?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn builder(config: OpenTelemetryConfig) -> TelemetryBuilder {
        TelemetryBuilder::new(config)
    }

    /// Create telemetry with full integration from configuration.
    ///
    /// This method sets up OpenTelemetry with all integrations enabled:
    /// - **Global tracer provider**: Enables `opentelemetry::global::tracer()` anywhere
    /// - **Global meter provider**: Enables `opentelemetry::global::meter()` anywhere
    /// - **Log bridge**: Routes `log::info!()` etc. to OpenTelemetry logs
    /// - **Tracing bridge**: Routes `tracing::info!()` etc. to OpenTelemetry logs
    ///
    /// This is the recommended way to initialize telemetry for most applications,
    /// as it provides seamless integration with the Rust logging ecosystem.
    ///
    /// # When to use `builder()` instead
    ///
    /// Use [`Telemetry::builder()`] if you need:
    /// - Custom exporters or processors
    /// - To disable specific bridges (e.g., if you have your own tracing subscriber)
    /// - Fine-grained control over which integrations are enabled
    ///
    /// # Effects on your application
    ///
    /// - **Sets the global logger**: Only one logger can be set per process. This will
    ///   fail if another logger (e.g., `env_logger`) is already installed.
    /// - **Sets the global tracing subscriber**: Only one subscriber can be set per
    ///   process. This will fail if another subscriber is already installed.
    /// - **Filters apply**: Both bridges respect `RUST_LOG` for filtering (defaults to `info`).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use apollo_opentelemetry::{OpenTelemetryConfig, Telemetry};
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let config = OpenTelemetryConfig::default();
    /// let telemetry = Telemetry::new(config)?;
    ///
    /// // Now all logging goes through OpenTelemetry
    /// log::info!("This becomes an OpenTelemetry log record");
    /// # Ok(())
    /// # }
    /// ```
    pub fn new(config: OpenTelemetryConfig) -> Result<Self, InitError> {
        Self::builder(config).with_globals().build()
    }

    /// Get a reference to the tracer provider, if tracing is enabled.
    ///
    /// Returns `None` if no tracer configuration was provided and no
    /// span exporters were added programmatically.
    pub fn tracer_provider(&self) -> Option<&SdkTracerProvider> {
        self.tracer_provider.as_ref()
    }

    /// Get a reference to the meter provider, if metrics are enabled.
    ///
    /// Returns `None` if no meter configuration was provided and no
    /// metric views were added programmatically.
    pub fn meter_provider(&self) -> Option<&SdkMeterProvider> {
        self.meter_provider.as_ref()
    }

    /// Get a reference to the logger provider, if logging is enabled.
    ///
    /// Returns `None` if no logger configuration was provided and no
    /// log exporters were added programmatically.
    pub fn logger_provider(&self) -> Option<&SdkLoggerProvider> {
        self.logger_provider.as_ref()
    }

    /// Explicitly shut down all telemetry providers.
    ///
    /// This flushes any buffered telemetry data and releases resources.
    /// It is called automatically when the `Telemetry` instance is dropped,
    /// but can be called explicitly for more control over shutdown timing.
    ///
    /// If the providers were registered as global providers, the global
    /// provider will continue to reference the shut-down provider, which
    /// will act as a no-op for any subsequent operations.
    ///
    /// After calling `shutdown()`, the providers are no longer available
    /// and subsequent calls to `tracer_provider()`, `meter_provider()`,
    /// and `logger_provider()` will return `None`.
    pub fn shutdown(&mut self) {
        // Take providers before any closure to avoid borrowing issues
        let tracer_provider = self.tracer_provider.take();
        let meter_provider = self.meter_provider.take();
        let logger_provider = self.logger_provider.take();

        // Shutdown order: traces first, then metrics, then logs
        let shutdown = move || {
            if let Some(provider) = tracer_provider {
                let _ = provider.shutdown();
            }
            if let Some(provider) = meter_provider {
                let _ = provider.shutdown();
            }
            if let Some(provider) = logger_provider {
                let _ = provider.shutdown();
            }
        };

        // In a multi-thread tokio runtime, use block_in_place to move blocking work off the
        // async worker thread. This prevents blocking the executor while waiting for shutdown.
        //
        // For current_thread runtimes or non-tokio contexts, call shutdown directly. The non-async
        // BatchSpanProcessor we use runs on a dedicated OS thread, so blocking here is safe.
        //
        // TODO: When switching to the async BatchSpanProcessor (span_processor_with_async_runtime),
        // detect runtime flavor at construction time and pass `TokioCurrentThread` for current_thread
        // or `Tokio` for multi_thread. This handles threading correctly from the start.
        // See: https://github.com/open-telemetry/opentelemetry-rust/blob/v0.31.0/opentelemetry-sdk/src/runtime.rs
        if let Ok(rt) = tokio::runtime::Handle::try_current()
            && rt.runtime_flavor() == RuntimeFlavor::MultiThread
        {
            tokio::task::block_in_place(shutdown);
        } else {
            shutdown();
        }
    }
}

impl Drop for Telemetry {
    fn drop(&mut self) {
        self.shutdown();
    }
}

#[cfg(test)]
mod tests {
    use apollo_configuration::parse_yaml;
    use opentelemetry::trace::TracerProvider;
    use opentelemetry_sdk::error::OTelSdkResult;
    use std::time::Duration;

    use super::*;

    #[test]
    fn none_has_no_providers() {
        let telemetry = Telemetry::none();

        assert!(telemetry.tracer_provider().is_none());
        assert!(telemetry.meter_provider().is_none());
        assert!(telemetry.logger_provider().is_none());
    }

    #[test]
    fn build_disabled_config() {
        let config: OpenTelemetryConfig = parse_yaml(
            indoc::indoc! {"
                disabled: true
                tracer_provider:
                  processors:
                    - batch:
                        exporter:
                          console: {}
            "},
            &Default::default(),
        )
        .unwrap();

        let telemetry = Telemetry::new(config).unwrap();

        // Disabled config should have no providers
        assert!(telemetry.tracer_provider().is_none());
        assert!(telemetry.meter_provider().is_none());
        assert!(telemetry.logger_provider().is_none());
    }

    #[test]
    fn builder_does_not_register_globally_by_default() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let builder = TelemetryBuilder::new(config);
        assert!(!builder.set_global_tracer);
        assert!(!builder.set_global_meter);
        assert!(!builder.set_global_propagator);
    }

    #[test]
    fn builder_with_global_propagator_flag() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let builder = Telemetry::builder(config).with_global_propagator();
        assert!(builder.set_global_propagator);
        let _telemetry = builder.build().unwrap();
    }

    #[test]
    fn builder_with_global_tracer_flag() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let builder = Telemetry::builder(config).with_global_tracer_provider();
        assert!(builder.set_global_tracer);
        let _telemetry = builder.build().unwrap();
    }

    #[test]
    fn builder_with_global_meter_flag() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let builder = Telemetry::builder(config).with_global_meter_provider();
        assert!(builder.set_global_meter);
        let _telemetry = builder.build().unwrap();
    }

    #[test]
    fn builder_with_resource_builder() {
        use opentelemetry::KeyValue;
        use opentelemetry_sdk::Resource;

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let _telemetry = Telemetry::builder(config)
            .with_resource_builder(
                Resource::builder()
                    .with_service_name("test-service")
                    .with_attributes([KeyValue::new("test.attr", "test-value")]),
            )
            .build()
            .unwrap();

        // Telemetry builds successfully with custom resource
        assert!(_telemetry.tracer_provider().is_some());
        assert!(_telemetry.meter_provider().is_some());
        assert!(_telemetry.logger_provider().is_some());
    }

    #[test]
    fn builder_with_resource_builder_overrides_config() {
        use opentelemetry::KeyValue;
        use opentelemetry_sdk::Resource;

        // Config has a resource attribute
        let config: OpenTelemetryConfig = parse_yaml(
            indoc::indoc! {"
                resource:
                  attributes:
                    - name: from.config
                      value: config-value
            "},
            &Default::default(),
        )
        .unwrap();

        // Builder resource should override config resource
        let _telemetry = Telemetry::builder(config)
            .with_resource_builder(
                Resource::builder()
                    .with_service_name("override-service")
                    .with_attributes([KeyValue::new("from.builder", "builder-value")]),
            )
            .build()
            .unwrap();

        assert!(_telemetry.tracer_provider().is_some());
    }

    #[test]
    fn shutdown_clears_providers() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let mut telemetry = Telemetry::builder(config).build().unwrap();

        telemetry.shutdown();

        assert!(telemetry.tracer_provider().is_none());
        assert!(telemetry.meter_provider().is_none());
        assert!(telemetry.logger_provider().is_none());
    }

    #[test]
    fn shutdown_is_idempotent() {
        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let mut telemetry = Telemetry::builder(config).build().unwrap();

        telemetry.shutdown();
        telemetry.shutdown(); // Should not panic

        assert!(telemetry.tracer_provider().is_none());
    }

    #[cfg(feature = "otlp")]
    #[test]
    fn global_tracer_set_and_shutdown() {
        use opentelemetry::trace::Tracer;

        let config: OpenTelemetryConfig = parse_yaml(
            indoc::indoc! {"
                tracer_provider:
                  processors:
                    - batch:
                        exporter:
                          console: {}
            "},
            &Default::default(),
        )
        .unwrap();

        // Create telemetry with global tracer provider
        let telemetry = Telemetry::builder(config)
            .with_global_tracer_provider()
            .build()
            .unwrap();

        // Verify the global tracer is working (can create a tracer and span)
        let tracer = global::tracer("test");
        let _span = tracer.start("test-span");

        // Drop the telemetry - this should shutdown the global provider
        drop(telemetry);

        // After shutdown, the global still references the provider but operations are noops
        let tracer = global::tracer("test-after-shutdown");
        let _span = tracer.start("noop-span");
    }

    #[cfg(feature = "otlp")]
    #[test]
    fn global_meter_set_and_shutdown() {
        let config: OpenTelemetryConfig = parse_yaml(
            indoc::indoc! {"
                meter_provider:
                  readers:
                    - periodic:
                        exporter:
                          otlp_http:
                            endpoint: http://localhost:4318
            "},
            &Default::default(),
        )
        .unwrap();

        // Create telemetry with global meter provider
        let telemetry = Telemetry::builder(config)
            .with_global_meter_provider()
            .build()
            .unwrap();

        // Verify the global meter is working (can create a meter and instrument)
        let meter = global::meter("test");
        let counter = meter.u64_counter("test_counter").build();
        counter.add(1, &[]);

        // Drop the telemetry - this should shutdown the global provider
        drop(telemetry);

        // After shutdown, the global still references the provider but operations are noops
        let meter = global::meter("test-after-shutdown");
        let counter = meter.u64_counter("noop_counter").build();
        counter.add(1, &[]);
    }

    #[cfg(feature = "otlp")]
    #[test]
    fn explicit_shutdown() {
        let config: OpenTelemetryConfig = parse_yaml(
            indoc::indoc! {"
                tracer_provider:
                  processors:
                    - batch:
                        exporter:
                          otlp_http:
                            endpoint: http://localhost:4318
            "},
            &Default::default(),
        )
        .unwrap();

        let mut telemetry = Telemetry::builder(config)
            .with_global_tracer_provider()
            .build()
            .unwrap();

        // Call shutdown explicitly
        telemetry.shutdown();

        assert!(telemetry.tracer_provider().is_none());
    }

    // Test that shutdown() uses block_in_place to avoid blocking the async runtime.
    //
    // Problem: OTel exporters may perform blocking I/O during shutdown (e.g., flushing
    // spans over the network). Without block_in_place, this blocks the worker thread.
    //
    // Setup:
    // - Tokio runtime with 1 worker thread
    // - Custom exporter that blocks for 1 second during shutdown
    // - Timer task that increments a counter every 10ms
    //
    // How it works:
    // 1. Spawn a timer task incrementing a counter every 10ms
    // 2. Spawn a task that drops Telemetry (triggers blocking shutdown)
    // 3. Wait for shutdown to complete, then check the counter
    //
    // Expected:
    // - WITH block_in_place: Timer runs during shutdown, counter reaches ~100
    // - WITHOUT block_in_place: Worker blocked, counter stays at ~0
    #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
    async fn shutdown_in_async_context() {
        use std::sync::Arc;
        use std::sync::atomic::{AtomicUsize, Ordering};

        // Test exporter that simulates slow network I/O during shutdown
        #[derive(Debug)]
        struct BlockingExporter;

        impl opentelemetry_sdk::trace::SpanExporter for BlockingExporter {
            async fn export(
                &self,
                _batch: Vec<opentelemetry_sdk::trace::SpanData>,
            ) -> opentelemetry_sdk::error::OTelSdkResult {
                Ok(())
            }

            fn shutdown_with_timeout(&mut self, _timeout: Duration) -> OTelSdkResult {
                // Simulate slow network flush - blocks thread for 1 second
                std::thread::sleep(Duration::from_millis(1000));
                Ok(())
            }
        }

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_simple_span_exporter(BlockingExporter)
            .build()
            .unwrap();

        // Counter incremented by timer task running concurrently with shutdown
        let counter = Arc::new(AtomicUsize::new(0));
        let counter_clone = counter.clone();

        // Timer task: increments counter every 10ms (needs worker thread to run)
        let _timer_task = tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_millis(10));
            loop {
                interval.tick().await;
                counter_clone.fetch_add(1, Ordering::SeqCst);
            }
        });

        // Drop task: triggers blocking shutdown on worker thread
        let drop_task = tokio::spawn(async move {
            drop(telemetry);
        });

        drop_task.await.unwrap();

        // Verify timer ran during 1-second shutdown
        // With block_in_place: ~100 ticks. Without: ~0 ticks.
        let final_count = counter.load(Ordering::SeqCst);
        assert!(
            final_count >= 10,
            "Timer should have run during shutdown (got {} ticks)",
            final_count
        );
    }

    // Verify shutdown works in a single-threaded tokio runtime using spawn_blocking.
    #[tokio::test(flavor = "current_thread")]
    async fn shutdown_in_single_threaded_runtime() {
        let config = OpenTelemetryConfig::default();
        let mut telemetry = Telemetry::builder(config).build().unwrap();

        // This should not panic
        telemetry.shutdown();
    }

    #[test]
    fn builder_with_simple_span_exporter() {
        use opentelemetry::trace::Tracer;
        use opentelemetry_sdk::trace::InMemorySpanExporter;

        let exporter = InMemorySpanExporter::default();
        let exporter_clone = exporter.clone();

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_simple_span_exporter(exporter)
            .build()
            .unwrap();

        // Create a span
        let tracer = telemetry.tracer_provider().unwrap().tracer("test");
        let _span = tracer.start("test-span");
        drop(_span);

        // Simple exporter exports synchronously
        let spans = exporter_clone.get_finished_spans().unwrap();
        assert_eq!(spans.len(), 1);
        assert_eq!(spans[0].name.as_ref(), "test-span");
    }

    #[test]
    fn builder_with_batch_span_exporter() {
        use opentelemetry::trace::Tracer;
        use opentelemetry_sdk::trace::InMemorySpanExporter;

        let exporter = InMemorySpanExporter::default();
        let exporter_clone = exporter.clone();

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let mut telemetry = Telemetry::builder(config)
            .with_batch_span_exporter(exporter)
            .build()
            .unwrap();

        // Create a span
        let tracer = telemetry.tracer_provider().unwrap().tracer("test");
        let _span = tracer.start("batch-test-span");
        drop(_span);

        // Force flush to export batched spans
        telemetry.tracer_provider().unwrap().force_flush().unwrap();

        let spans = exporter_clone.get_finished_spans().unwrap();
        assert_eq!(spans.len(), 1);
        assert_eq!(spans[0].name.as_ref(), "batch-test-span");

        telemetry.shutdown();
    }

    #[test]
    fn builder_with_span_processor() {
        use opentelemetry::trace::Tracer;
        use opentelemetry_sdk::trace::{InMemorySpanExporter, SimpleSpanProcessor};

        let exporter = InMemorySpanExporter::default();
        let exporter_clone = exporter.clone();
        let processor = SimpleSpanProcessor::new(exporter);

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_span_processor(processor)
            .build()
            .unwrap();

        // Create a span
        let tracer = telemetry.tracer_provider().unwrap().tracer("test");
        let _span = tracer.start("processor-test-span");
        drop(_span);

        let spans = exporter_clone.get_finished_spans().unwrap();
        assert_eq!(spans.len(), 1);
        assert_eq!(spans[0].name.as_ref(), "processor-test-span");
    }

    #[test]
    fn builder_with_view() {
        use opentelemetry::metrics::MeterProvider;

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_view(|_instrument: &Instrument| None)
            .build()
            .unwrap();

        // Verify we can create instruments through the meter provider
        let meter = telemetry.meter_provider().unwrap().meter("test");
        let counter = meter.u64_counter("test_counter").build();
        counter.add(1, &[]);
    }

    #[test]
    fn builder_with_periodic_reader() {
        use opentelemetry::metrics::MeterProvider;
        use opentelemetry_sdk::metrics::{InMemoryMetricExporter, PeriodicReader};

        let exporter = InMemoryMetricExporter::default();
        let reader = PeriodicReader::builder(exporter.clone()).build();

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_periodic_reader(reader)
            .build()
            .unwrap();

        let meter_provider = telemetry.meter_provider().unwrap();
        let meter = meter_provider.meter("test");
        let counter = meter.u64_counter("test_counter").build();
        counter.add(42, &[]);

        meter_provider.force_flush().unwrap();

        let metrics = exporter.get_finished_metrics().unwrap();
        assert!(!metrics.is_empty(), "expected metrics to be exported");
    }

    #[test]
    fn builder_with_simple_log_exporter() {
        use opentelemetry_sdk::logs::InMemoryLogExporter;

        let exporter = InMemoryLogExporter::default();

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_simple_log_exporter(exporter)
            .build()
            .unwrap();

        assert!(telemetry.logger_provider().is_some());
    }

    #[test]
    fn builder_with_batch_log_exporter() {
        use opentelemetry_sdk::logs::InMemoryLogExporter;

        let exporter = InMemoryLogExporter::default();

        let config: OpenTelemetryConfig = parse_yaml("{}", &Default::default()).unwrap();
        let telemetry = Telemetry::builder(config)
            .with_batch_log_exporter(exporter)
            .build()
            .unwrap();

        assert!(telemetry.logger_provider().is_some());
    }
}