Document recorder initialization invariant for metrics.

Clarify that telemetry must be initialized before any metric emission so cached handles bind to the production recorder.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Mallets

quickwit/quickwit-metrics/src/counter.rs

@@ -33,6 +33,18 @@ static COUNTERS: LazyLock<DashMap<u64, Arc<CounterInner>>> = LazyLock::new(DashM
 /// the static metadata, key, and recorder handle that live for the
 /// lifetime of the process.
 ///
+/// # Recorder-binding invariant
+///
+/// The `metrics::Counter` handle returned by `register_counter` is
+/// permanently bound to whichever [`metrics::Recorder`] is active at
+/// first-access time. If this function is called before the production
+/// recorder is installed (e.g. while the noop default is still active),
+/// the cached handle will silently discard all subsequent increments.
+///
+/// **Callers must ensure that the global recorder is installed before
+/// any metric is first accessed.** In Quickwit this is guaranteed by
+/// `init_telemetry()` running before any `LazyLock<Counter>` is forced.
+///
 /// Prefer the `counter!` macro over calling this directly.
 #[doc(hidden)]
 pub fn __counter_get_or_register(

quickwit/quickwit-metrics/src/gauge.rs

@@ -34,6 +34,18 @@ static GAUGES: LazyLock<DashMap<u64, Arc<GaugeInner>>> = LazyLock::new(DashMap::
 /// the static metadata, key, and recorder handle that live for the
 /// lifetime of the process.
 ///
+/// # Recorder-binding invariant
+///
+/// The `metrics::Gauge` handle returned by `register_gauge` is
+/// permanently bound to whichever [`metrics::Recorder`] is active at
+/// first-access time. If this function is called before the production
+/// recorder is installed (e.g. while the noop default is still active),
+/// the cached handle will silently discard all subsequent mutations.
+///
+/// **Callers must ensure that the global recorder is installed before
+/// any metric is first accessed.** In Quickwit this is guaranteed by
+/// `init_telemetry()` running before any `LazyLock<Gauge>` is forced.
+///
 /// Prefer the `gauge!` macro over calling this directly.
 #[doc(hidden)]
 pub fn __gauge_get_or_register(

quickwit/quickwit-metrics/src/histogram.rs

@@ -48,6 +48,18 @@ static HISTOGRAMS: LazyLock<DashMap<u64, Arc<HistogramInner>>> = LazyLock::new(D
 /// the static metadata, key, and recorder handle that live for the
 /// lifetime of the process.
 ///
+/// # Recorder-binding invariant
+///
+/// The `metrics::Histogram` handle returned by `register_histogram` is
+/// permanently bound to whichever [`metrics::Recorder`] is active at
+/// first-access time. If this function is called before the production
+/// recorder is installed (e.g. while the noop default is still active),
+/// the cached handle will silently discard all subsequent recordings.
+///
+/// **Callers must ensure that the global recorder is installed before
+/// any metric is first accessed.** In Quickwit this is guaranteed by
+/// `init_telemetry()` running before any `LazyLock<Histogram>` is forced.
+///
 /// Prefer the `histogram!` macro over calling this directly.
 #[doc(hidden)]
 pub fn __histogram_get_or_register(

quickwit/quickwit-telemetry-exporters/src/lib.rs

@@ -90,6 +90,11 @@ pub(crate) fn startup_env_filter(level: Level) -> anyhow::Result<EnvFilter> {
 pub(crate) type ReloadLayer =
     tracing_subscriber::reload::Layer<EnvFilter, tracing_subscriber::Registry>;
 
+/// Initializes logging/tracing/metrics providers for the process.
+///
+/// NOTE: this function must be called before any metric is emitted so metric handles
+/// are registered against the production recorder instead of a noop/default
+/// recorder.
 pub fn init_telemetry(
     service_version: &str,
     level: Level,