cqlite-core 0.17.0

//! Observability foundation (epic #1031, issues #1032 + #1038).
//!
//! This module is the single shared foundation every other observability issue
//! builds on. It owns OpenTelemetry initialisation, the `CQLITE_OTEL_*` config,
//! the metric-naming [`catalog`], the error-rate schema ([`ObsErrorCategory`] +
//! [`record_error`]), and graceful shutdown — and it is designed so that
//! **instrumentation call sites are identical whether or not the
//! `observability` feature is enabled.** When the feature is off, every helper
//! here compiles to a no-op and `cargo tree -p cqlite-core` links no
//! OpenTelemetry crates.
//!
//! # The contract for downstream issues (#1033–#1043)
//!
//! Downstream code MUST go through this module rather than touching
//! `opentelemetry`/`tracing-opentelemetry` directly, so telemetry stays
//! consistent and zero-cost-when-off:
//!
//! **Initialisation (CLI #1033, Flight #1041, bindings #1039/#1040):**
//! ```ignore
//! let cfg = observability::ObservabilityConfig::from_env();
//! let _guard = observability::init(cfg)?;            // RAII; flushes on drop
//! // compose the tracing layer into your own subscriber (feature-gated):
//! # #[cfg(feature = "observability")]
//! tracing_subscriber::registry()
//!     .with(tracing_subscriber::fmt::layer())
//!     .with(observability::tracing_layer())
//!     .init();
//! ```
//!
//! **Spans (read/query/write/compaction #1034–#1037):** use the ordinary
//! `tracing` macros (`#[tracing::instrument]`, `tracing::info_span!`) — they are
//! always available and the OTel layer bridges them when active. Do NOT create
//! per-cell spans on hot paths; aggregate with metrics instead.
//!
//! **Metrics:** call [`add_counter`], [`record_histogram`], [`record_gauge`]
//! with a name from [`catalog`] and bounded [`Attr`] attributes whose keys come
//! from [`catalog::attr`]:
//! ```ignore
//! use cqlite_core::observability::{self as obs, catalog, AttrValue};
//! obs::add_counter(catalog::READ_ROWS, n, &[(catalog::attr::SSTABLE_FORMAT, "bti".into())]);
//! obs::record_histogram(catalog::QUERY_DURATION, elapsed.as_secs_f64(), &[]);
//! ```
//!
//! **Errors (#1038):** at every boundary instrumented by #1034–#1037, call
//! [`record_error`] when an error escapes — it increments
//! [`catalog::ERRORS_TOTAL`] keyed by the bounded `{category, subsystem}` label
//! set and marks the active span errored. Never attach the raw error message.
//!
//! # Why was this query slow? (issue #1707)
//!
//! [`catalog::READ_DURATION`] tells you a read was slow. These four histograms tell
//! you WHERE the time went, so the next step is a decision rather than a profiler:
//!
//! 1. **Localise with `cqlite.read.phase.*`.** One sample per phase per completed
//!    scan — [`catalog::READ_PHASE_IO`], [`catalog::READ_PHASE_DECOMPRESS`],
//!    [`catalog::READ_PHASE_DECODE`], [`catalog::READ_PHASE_MERGE`]. Compare them
//!    against EACH OTHER:
//!    * **io dominant** → disk / page-cache bound (cold storage, evicted cache, a
//!      network filesystem). Decode and merge tuning cannot help this read.
//!    * **decompress dominant** → chunk length / compressor choice, or the same
//!      chunks being decompressed repeatedly (a decompressed-chunk cache too small
//!      for the scan's window).
//!    * **decode dominant** → normally HEALTHY on a warm scan (decode is the CPU
//!      work of a read). Suspicious only when it grows relative to the rows
//!      DELIVERED: wide partitions, many collection/UDT cells, or a schema-less
//!      fallback decode.
//!    * **merge dominant** → too many overlapping generations, or heavy reconcile
//!      (tombstones, LWW collapse). Cross-check [`catalog::COMPACTION_LAG`]; the
//!      recv-wait is already excluded, so this really is merge work and not a
//!      producer starving.
//! 2. **Read the ABSENCES, they are informative.** A phase that never ran records NO
//!    sample rather than `0.0`: no `decompress` series means the SSTable is
//!    uncompressed (the #1406 write-surface shape), and no `merge` series means the
//!    read had a single generation. Absence is a fact about the read; `0.0` would be
//!    a claim that a measurement was taken.
//! 3. **Know which surfaces are instrumented before you read an absence.** The
//!    phases come from the STREAMING scan surfaces and the streaming
//!    cross-generation merge. The materializing `SSTableManager::scan`, the BIG
//!    reverse-clustering scan, the BTI trie walk, point reads and compaction reads
//!    emit [`catalog::READ_DURATION`] with NO phase series at all — for those, an
//!    empty breakdown means NOT MEASURED, never "fast". The full list, and why
//!    instrumenting them needs async-safe propagation rather than another seam, is in
//!    [`read_phase`]'s "Coverage boundary" section.
//! 4. **Check fd pressure.** [`catalog::READER_FDS_OPEN`] is what the readers hold
//!    (exact, every platform, no `/proc`); [`catalog::PROC_FDS`] is the whole process
//!    (sampled ~2s, Linux). A reader level climbing toward `ulimit -n` explains
//!    latency that is really queueing behind failing/retried opens — and it is
//!    visible BEFORE the first `EMFILE`. `PROC_FDS` minus the reader level is roughly
//!    the non-reader footprint (sockets, WAL).
//! 5. **Check startup / durability stalls.** [`catalog::WAL_SIZE`] should saw-tooth;
//!    a level that only climbs means flushes are not keeping up, and next open's
//!    [`catalog::WAL_RECOVERY_DURATION`] grows with it. A slow FIRST query after a
//!    restart is usually WAL recovery, not the read path.
//!
//! **The accounting caveat, and it matters for step 1:** the read pipeline is
//! CONCURRENT — an IO/decompress feed thread, a blocking parse thread, a merge
//! producer thread — so the phases OVERLAP in wall-clock and DO NOT sum to
//! `read.duration`. Their sum can even exceed it. They are per-phase TOTALS for
//! attribution ("which phase dominates, and how did that move between two runs?"),
//! never a decomposition of latency, and a dashboard that stacks them as a
//! breakdown of wall time will mislead. Same caveat as the #2819 `stream_*`
//! sub-phases.
//!
//! # Always-compiled vs feature-gated
//!
//! [`catalog`], [`config`], the [`ObsErrorCategory`] taxonomy, and the helper
//! signatures here are ALWAYS compiled (they pull in no OTel types), so call
//! sites and tests build in any configuration. Only the exporter/runtime wiring
//! ([`otel`]) is gated behind `observability`.

pub mod catalog;
pub mod config;
mod error_schema;
pub mod operator_docs;
mod operator_docs_annotations;
pub mod partition_access;
// Read-path metric emission at batch granularity (issue #1701): the accumulator
// that makes cqlite.read.{rows,bytes,partitions,duration} live instruments
// instead of documented-but-never-written ones.
pub(crate) mod read_metrics;
// Per-SCAN read-phase accumulator (issue #1707): the io/decompress/decode/merge
// buckets `ReadOpMeter` emits as `cqlite.read.phase.*` when a scan completes.
//
// `pub(crate)`, NOT `pub`: its seams live across the storage layer but entirely
// INSIDE this crate, and no downstream crate consumes any of it. That is the
// difference from `stream_subphase`, which is genuinely `pub` because
// `cqlite-flight` installs its sink. Exporting this module made ~12 items part of
// `cqlite-core`'s public API — a surface nobody asked for, that nothing in this
// repo detects a change to (#3366), and that would then have to be kept
// compatible. The ONE item a test outside the crate needs is re-exported below.
pub(crate) mod read_phase;
pub mod stream_subphase;

pub use config::{ObservabilityConfig, ObservabilityConfigBuilder, OtelProtocol};
pub use error_schema::ObsErrorCategory;
// `ReadPhaseGuard` is deliberately NOT re-exported: it is only ever named as
// `install`'s return type, which callers bind with `let _g = …`.
pub(crate) use read_phase::{ReadPhase, ReadPhaseTimings};

/// TEST-ONLY arming surface for the read-phase io delay (issue #1707), the ONE
/// item of the crate-internal [`read_phase`] module an out-of-crate test needs.
///
/// Hidden from the rendered docs and compiled out entirely unless
/// `observability-testing` (or `cfg(test)`) is on, so a production build of
/// `cqlite-core` exports nothing here.
#[cfg(any(test, feature = "observability-testing"))]
#[doc(hidden)]
pub use read_phase::io_delay;
pub use stream_subphase::{StreamSubPhase, StreamSubPhaseGuard, StreamSubPhaseTimings};

use crate::error::{Error, Result};

#[cfg(feature = "observability")]
mod otel;

// Instrument construction, split from `otel.rs` per the campsite rule (#1116).
#[cfg(feature = "observability")]
mod otel_instruments;

#[cfg(feature = "observability")]
pub use otel::{init, tracing_layer, ObservabilityGuard};

/// Shared in-memory OTLP capture harness for observability tests (issue #1043).
///
/// Gated behind the `observability-testing` feature, which pulls in the OTel
/// SDK's in-memory exporters (`InMemorySpanExporter` / `InMemoryMetricExporter`)
/// via `opentelemetry_sdk/testing`. Public so integration tests and future child
/// issues can reuse the same fixture API to assert span trees and metric
/// names/units/attributes. Production `observability` builds never compile this,
/// so they never link the SDK's testing surface.
#[cfg(feature = "observability-testing")]
pub mod testing;

/// A bounded attribute value for catalog metrics.
///
/// Mirrors the small set of types OpenTelemetry attributes accept, but is always
/// available regardless of the `observability` feature so instrumentation call
/// sites compile identically when telemetry is off. Keep values bounded
/// (prefer [`AttrValue::StaticStr`] / numbers); never feed unbounded data such
/// as raw error messages, partition keys, or full query text.
#[derive(Debug, Clone)]
pub enum AttrValue {
    /// An owned string. Use only for genuinely bounded values.
    Str(String),
    /// A `&'static str` — the preferred, allocation-free form.
    StaticStr(&'static str),
    /// A signed integer.
    Int(i64),
    /// A floating-point value.
    Float(f64),
    /// A boolean.
    Bool(bool),
}

impl From<&'static str> for AttrValue {
    fn from(v: &'static str) -> Self {
        AttrValue::StaticStr(v)
    }
}
impl From<String> for AttrValue {
    fn from(v: String) -> Self {
        AttrValue::Str(v)
    }
}
impl From<i64> for AttrValue {
    fn from(v: i64) -> Self {
        AttrValue::Int(v)
    }
}
impl From<u64> for AttrValue {
    fn from(v: u64) -> Self {
        AttrValue::Int(v as i64)
    }
}
impl From<f64> for AttrValue {
    fn from(v: f64) -> Self {
        AttrValue::Float(v)
    }
}
impl From<bool> for AttrValue {
    fn from(v: bool) -> Self {
        AttrValue::Bool(v)
    }
}

/// A single bounded metric attribute: a `&'static str` key (always from
/// [`catalog::attr`]) paired with a bounded [`AttrValue`].
pub type Attr = (&'static str, AttrValue);

#[cfg(feature = "observability")]
fn to_key_values(attrs: &[Attr]) -> Vec<opentelemetry::KeyValue> {
    use opentelemetry::{KeyValue, Value};
    attrs
        .iter()
        .map(|(k, v)| {
            let value = match v {
                AttrValue::Str(s) => Value::from(s.clone()),
                AttrValue::StaticStr(s) => Value::from(*s),
                AttrValue::Int(i) => Value::from(*i),
                AttrValue::Float(f) => Value::from(*f),
                AttrValue::Bool(b) => Value::from(*b),
            };
            KeyValue::new(*k, value)
        })
        .collect()
}

/// Add `value` to the monotonic counter identified by a [`catalog`] name, with
/// bounded [`Attr`] attributes. No-op (and zero-cost) when the `observability`
/// feature is off.
#[inline]
pub fn add_counter(name: &'static str, value: u64, attrs: &[Attr]) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            otel::add_counter(name, value, &to_key_values(attrs));
        } else {
            let _ = (name, value, attrs);
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = (name, value, attrs);
    }
}

/// Whether metrics are actually being collected — the `observability` feature is
/// compiled in AND a meter provider is installed (`otel::metrics_active`). Every
/// `record_*` here already gates on this, so it is a no-op when false; exposing it
/// lets a caller SKIP building per-request timing state whose samples would only
/// be discarded (issue #2819 M1 — the "zero-cost when the meter is off" promise).
#[inline]
pub fn metrics_active() -> bool {
    #[cfg(feature = "observability")]
    {
        otel::metrics_active()
    }
    #[cfg(not(feature = "observability"))]
    {
        false
    }
}

/// Record `value` into the histogram identified by a [`catalog`] name (durations
/// in seconds, sizes in bytes — see the catalog docs). No-op when off.
#[inline]
pub fn record_histogram(name: &'static str, value: f64, attrs: &[Attr]) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            otel::record_histogram(name, value, &to_key_values(attrs));
        } else {
            let _ = (name, value, attrs);
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = (name, value, attrs);
    }
}

/// Record `value` for the gauge identified by a [`catalog`] name (a current
/// value such as in-flight count or open SSTables). No-op when off.
#[inline]
pub fn record_gauge(name: &'static str, value: i64, attrs: &[Attr]) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            otel::record_gauge(name, value, &to_key_values(attrs));
        } else {
            let _ = (name, value, attrs);
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = (name, value, attrs);
    }
}

/// Record an error that escaped a critical section (issue #1038).
///
/// Increments [`catalog::ERRORS_TOTAL`] keyed by the bounded
/// `{cqlite.error.category, cqlite.subsystem}` label set and marks the active
/// span as errored. `subsystem` is a `&'static str` (e.g. `"reader"`,
/// `"query"`, `"write"`, `"compaction"`) so its value space stays bounded. The
/// raw error message is never recorded. No-op when the `observability` feature
/// is off.
#[inline]
pub fn record_error(err: &Error, subsystem: &'static str) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            let attrs = [
                opentelemetry::KeyValue::new(
                    catalog::attr::ERROR_CATEGORY,
                    err.obs_category().as_str(),
                ),
                opentelemetry::KeyValue::new(catalog::attr::SUBSYSTEM, subsystem),
            ];
            otel::add_counter(catalog::ERRORS_TOTAL, 1, &attrs);
            otel::mark_span_error(err.obs_category());
        } else {
            let _ = (err, subsystem);
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = (err, subsystem);
    }
}

/// Record an error into [`catalog::ERRORS_TOTAL`] with EXTRA bounded attributes
/// beyond the canonical `{cqlite.error.category, cqlite.subsystem}` pair.
///
/// Identical to [`record_error`] but appends the caller-supplied `extra`
/// attributes to the same single counter increment (and still marks the active
/// span errored with the derived category). The extra keys MUST be bounded
/// (closed value sets), e.g. the Flight `do_get` abort taxonomy's
/// `cqlite.flight.abort_reason` (issue #2681) — never a raw message, ticket, or
/// key. No-op when the `observability` feature is off.
#[inline]
pub fn record_error_with_attrs(err: &Error, subsystem: &'static str, extra: &[Attr]) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            let mut attrs = to_key_values(extra);
            attrs.push(opentelemetry::KeyValue::new(
                catalog::attr::ERROR_CATEGORY,
                err.obs_category().as_str(),
            ));
            attrs.push(opentelemetry::KeyValue::new(
                catalog::attr::SUBSYSTEM,
                subsystem,
            ));
            otel::add_counter(catalog::ERRORS_TOTAL, 1, &attrs);
            otel::mark_span_error(err.obs_category());
        } else {
            let _ = (err, subsystem, extra);
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = (err, subsystem, extra);
    }
}

/// Mark the active span as errored WITHOUT counting the failure (issue #1704).
///
/// [`record_error`] does TWO things: it increments [`catalog::ERRORS_TOTAL`] and it
/// marks the active span errored. Those have different owners. The COUNT belongs to
/// the operation — exactly one per user-visible failure, which is why an inner step
/// whose caller records must not increment. The SPAN belongs to the call that opened
/// it, and an inner step that returns `Err` under an unmarked span reports a
/// successful-looking span for a failed operation.
///
/// Suppressing the whole of `record_error` therefore over-suppresses. This is the
/// span-only half, for a call site that defers only the counter. Gated identically to
/// [`record_error`] so the marked/unmarked decision cannot diverge between the two.
#[inline]
pub fn mark_span_error(err: &Error) {
    #[cfg(feature = "observability")]
    {
        if otel::metrics_active() {
            otel::mark_span_error(err.obs_category());
        } else {
            let _ = err;
        }
    }
    #[cfg(not(feature = "observability"))]
    {
        let _ = err;
    }
}

/// Convenience: run a `Result`-returning closure and [`record_error`] on the
/// `Err` path, returning the result unchanged. Lets call sites instrument an
/// operation without restructuring their error handling.
#[inline]
pub fn record_result<T>(subsystem: &'static str, result: Result<T>) -> Result<T> {
    if let Err(e) = &result {
        record_error(e, subsystem);
    }
    result
}

/// Parent a `tracing` span under a remote trace described by a W3C
/// [`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header)
/// header string (issues #1039/#1040/#1041).
///
/// Hosts (the Python/Node bindings, the Flight server) frequently receive an
/// incoming `traceparent` from a caller's tracer and want the per-call CQLite
/// span to attach to that remote trace. This helper extracts the W3C trace
/// context with the standard [`TraceContextPropagator`] and sets it as the
/// parent of `span` via `tracing-opentelemetry`'s `set_parent`.
///
/// It is always callable: when the `observability` feature is off — or when
/// `traceparent` is `None`/empty/unparseable — it is a no-op, so call sites
/// stay identical across builds. Pass the per-open or per-call traceparent
/// straight from the binding boundary; never synthesise one.
#[inline]
pub fn set_span_parent_from_traceparent(span: &tracing::Span, traceparent: Option<&str>) {
    #[cfg(feature = "observability")]
    otel::set_span_parent_from_traceparent(span, traceparent);
    #[cfg(not(feature = "observability"))]
    {
        let _ = (span, traceparent);
    }
}

/// Inert observability guard returned by [`init`] when the `observability`
/// feature is disabled. Flushes and installs nothing.
#[cfg(not(feature = "observability"))]
#[derive(Debug)]
pub struct ObservabilityGuard {
    _private: (),
}

#[cfg(not(feature = "observability"))]
impl ObservabilityGuard {
    /// Always `false` for the inert guard.
    pub fn is_active(&self) -> bool {
        false
    }
    /// No-op flush.
    pub fn force_flush(&self) {}
}

/// Initialise observability from `cfg`. When the `observability` feature is
/// disabled this is a no-op (no OTel wiring) that returns an inert
/// [`ObservabilityGuard`], so callers (CLI, Flight, bindings) can call it
/// unconditionally.
///
/// It STILL plumbs `cfg.verify_presence_oracle` into the presence-oracle
/// false-negative verification switch (issue #2163, roborev r4): that switch is
/// an always-compiled storage-layer knob, independent of whether the OTel export
/// stack is linked, so a config-only build without the `observability` feature
/// can still enable the confirmation-scan correctness check (its counter emit is
/// simply a no-op in that build, per the module's zero-cost-when-off contract).
///
/// # Observability honesty (issue #1702, epic #1686)
///
/// When `cfg.enabled` is `true` this build CANNOT export anything, so it emits
/// ONE `WARN` naming the knob, the missing cargo feature and the consequence.
/// Without it, `CQLITE_OTEL_ENABLED=1` is a completely silent no-op and an
/// operator cannot tell "collector down / endpoint misconfigured" from "this
/// binary was built without the feature". It stays a warning, never an error:
/// degraded-but-running is the correct behavior — the defect was VISIBILITY.
#[cfg(not(feature = "observability"))]
#[inline]
pub fn init(cfg: ObservabilityConfig) -> Result<ObservabilityGuard> {
    crate::storage::sstable::reader::presence_verification::apply_config(
        cfg.verify_presence_oracle,
    );

    // Issue #1702. Emitted with `tracing::warn!`, not the `log` crate's `warn!`
    // as the issue text spells it (that literal spelling is deliberately avoided
    // here: the `logging_facade_tracing` guard scans this directory textually and
    // is not comment-aware, so writing it out trips the residual-macro check):
    // `cqlite-core` has no `log` dependency at all — its facade
    // is `tracing` (the #1706 log->tracing migration) — and `tracing` satisfies
    // the same constraint, since every host composes the fmt layer onto STDERR
    // so stdout stays clean for `--out json/csv` (issue #129).
    //
    // Fired unconditionally on each `init` call rather than behind a `Once`.
    // Every in-repo caller invokes `init` exactly once per process (CLI
    // `run_main`, the Flight server, `init_once` in both bindings), so "once at
    // init" is "once per process" for them — but that is a CONVENTION of those
    // callers, NOT something this function enforces. `cqlite-core` is a library:
    // an out-of-tree embedder that calls `init` per connection or per request
    // with `enabled = true` on a default build gets one WARN per call. A `Once`
    // would bound that, at the cost of making the warning unobservable to the
    // second of two tests in one binary; if per-call spam ever shows up in the
    // field, that is the tradeoff to revisit.
    //
    // `cfg.enabled` is the ONLY field a feature-off build silently discards, so
    // it is the only one that warns. `verify_presence_oracle` is genuinely
    // honored above. The remaining `CQLITE_OTEL_*` vars (endpoint, protocol,
    // service name/version, sampling ratio, timeout) are all subordinate to
    // `enabled`: with `enabled == false` they change nothing even in a
    // feature-ON build, so a separate warning for them would be noise, not
    // honesty. This omission is deliberate, not an oversight.
    //
    // Wording note: `init` receives an already-RESOLVED config and cannot know
    // which source enabled it (the CLI accepts `CQLITE_OTEL_ENABLED`, the
    // `--otel-enabled` flag, and a config file, all feeding this one field), so
    // the message must not assert that the env var is set. It names the env var
    // as the common spelling — operators grep for it — without claiming
    // provenance.
    //
    // The warning carries NO fields, deliberately (roborev r2, blocker). An
    // earlier version attached `requested_endpoint = %cfg.endpoint`, i.e. a
    // user-controlled URL rendered verbatim by the fmt layer. That is two defect
    // classes in one field: an endpoint of the form
    // `http://user:pass@collector:4317` writes credentials into the log, and an
    // endpoint containing newlines/control characters can FORGE additional log
    // lines. Neither is sanitized here — the field is simply gone, which removes
    // the class instead of filtering it. Nothing diagnostic is lost: this build
    // never contacts the endpoint, and the message says so.
    if cfg.enabled {
        tracing::warn!(
            "OpenTelemetry export is ENABLED in configuration (CQLITE_OTEL_ENABLED / \
             --otel-enabled / config file) but this binary was built WITHOUT the \
             `observability` cargo feature: OpenTelemetry is compiled out, so NO \
             metrics and NO traces will be emitted and the OTLP endpoint is never \
             contacted — this is NOT a collector or endpoint problem. Rebuild with \
             `--features observability` to export telemetry, or disable \
             OpenTelemetry (e.g. CQLITE_OTEL_ENABLED=0, or drop --otel-enabled) \
             to silence this warning."
        );
    }

    Ok(ObservabilityGuard { _private: () })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn helpers_are_callable_in_any_build() {
        // These must compile and not panic regardless of feature state.
        add_counter(
            catalog::READ_ROWS,
            3,
            &[(catalog::attr::SSTABLE_FORMAT, "bti".into())],
        );
        record_histogram(catalog::QUERY_DURATION, 0.001, &[]);
        record_gauge(catalog::SSTABLES_OPEN, 2, &[]);
        let err = Error::corruption("x");
        record_error(&err, "reader");
        let ok: Result<u8> = record_result("reader", Ok(1));
        assert_eq!(ok.ok(), Some(1));
    }

    #[test]
    fn init_returns_guard() {
        // With the feature off this exercises the inert guard; with it on it
        // exercises the disabled-config inert path in otel::init.
        let cfg = ObservabilityConfig::builder().enabled(false).build();
        let guard = init(cfg).expect("init never fails for a disabled config");
        assert!(!guard.is_active());
        guard.force_flush();
    }

    #[test]
    fn attr_value_conversions() {
        assert!(matches!(AttrValue::from("s"), AttrValue::StaticStr("s")));
        assert!(matches!(AttrValue::from(1i64), AttrValue::Int(1)));
        assert!(matches!(AttrValue::from(2u64), AttrValue::Int(2)));
        assert!(matches!(AttrValue::from(true), AttrValue::Bool(true)));
    }
}