camel_component_api/
runtime_observability.rs

1//! `RuntimeObservability` — narrow trait exposing `metrics()` and `health()`
2//! to Endpoint consumers/producers. Defined per ADR-0012 §Signal-replacement-API
3//! and the Phase A closure spec
4//! (`docs/superpowers/specs/2026-06-05-adr-0012-closure-design.md`).
5//!
6//! **Why a separate trait:** `ComponentContext` carries `resolve_component`,
7//! `resolve_language`, `platform_service` — far more authority than an
8//! emitter needs. Passing `Arc<dyn ComponentContext>` would be a
9//! service-locator anti-pattern inviting future misuse. This trait exposes
10//! exactly the two observability surfaces an ADR-0012 emitter calls.
11
12use std::sync::Arc;
13
14use camel_api::{ComponentMetrics, MetricsCollector};
15
16use crate::{ComponentContext, HealthCheckRegistry};
17
18/// Narrow observability surface available to Endpoint consumers and producers.
19///
20/// Implemented blanket for every `T: ComponentContext`, so
21/// `CamelContext` (the spec's "DefaultRuntime") and any test ctx
22/// automatically satisfy this trait. Endpoints receive
23/// `Arc<dyn RuntimeObservability>` at `create_consumer` / `create_producer`
24/// time (per Phase A closure spec).
25///
26/// `Send + Sync` is mandatory — Endpoints spawn across tokio tasks.
27pub trait RuntimeObservability: Send + Sync {
28    /// Active metrics collector. Used for `increment_errors(route_id, label)`
29    /// per ADR-0012 categories (b′) and (e).
30    fn metrics(&self) -> Arc<dyn MetricsCollector>;
31
32    /// Active health-check registry. Used for
33    /// `force_unhealthy_for_route(route_id, name, reason)` per ADR-0012
34    /// category (g).
35    fn health(&self) -> Arc<dyn HealthCheckRegistry>;
36
37    /// Facade for the uniform component-operations family
38    /// (`camel_component_operations_total{component,operation,outcome}`,
39    /// dashboard-observability Task 4.1). The lever snapshot is baked in
40    /// at facade construction: the component series flow only with the
41    /// `[observability.metrics].components` lever on, while failures
42    /// always reach the non-disableable error family.
43    ///
44    /// Default: lever off — impls that do not override
45    /// `component_metrics_enabled()` (manual test runtimes AND any
46    /// context wired without a levers snapshot) keep the component
47    /// series suppressed and only forward errors. In production the
48    /// controller-path `ControllerComponentContext` overrides it with
49    /// the levers snapshot taken at pipeline assembly.
50    fn component_metrics(&self) -> ComponentMetrics {
51        ComponentMetrics::new(self.metrics(), false)
52    }
53}
54
55// Blanket impl: every ComponentContext is automatically a RuntimeObservability.
56// This covers `CamelContext` (production), `NoOpComponentContext` (tests),
57// and any future impl.
58//
59// No `?Sized` bound: ComponentContext itself requires Sized (the trait has
60// methods returning `Arc<dyn …>` which need a concrete owner type). If a
61// future dynamically-sized ctx is needed, add a separate explicit impl.
62impl<T: ComponentContext> RuntimeObservability for T {
63    fn metrics(&self) -> Arc<dyn MetricsCollector> {
64        <Self as ComponentContext>::metrics(self)
65    }
66
67    fn health(&self) -> Arc<dyn HealthCheckRegistry> {
68        <Self as ComponentContext>::health(self)
69    }
70
71    fn component_metrics(&self) -> ComponentMetrics {
72        ComponentMetrics::new(
73            <Self as ComponentContext>::metrics(self),
74            <Self as ComponentContext>::component_metrics_enabled(self),
75        )
76    }
77}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82
83    #[test]
84    fn runtime_observability_is_send_sync() {
85        fn assert_send_sync<T: Send + Sync + ?Sized>() {}
86        assert_send_sync::<dyn RuntimeObservability>();
87    }
88}
camel_component_api/runtime_observability.rs

camel_component_api/
runtime_observability.rs
