Skip to main content

matier_core/
observer.rs

1//! Instrumentation hooks.
2
3use std::time::Duration;
4
5use crate::origin::{OriginKey, Protocol};
6
7/// Connection establishment phase.
8#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
9pub enum ConnectPhase {
10    Dns,
11    Tcp,
12    Tls,
13}
14
15impl ConnectPhase {
16    /// Stable lowercase name.
17    #[must_use]
18    pub const fn as_str(self) -> &'static str {
19        match self {
20            Self::Dns => "dns",
21            Self::Tcp => "tcp",
22            Self::Tls => "tls",
23        }
24    }
25}
26
27/// Why the pool changed the number of connections to an origin (see `Observer::pool_scaled`).
28#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
29pub enum ScaleReason {
30    /// A connection was saturated (busy actor, dispatch delay, full of streams): one more was dialed.
31    Saturated,
32    /// Requests were waiting for a stream slot and a connection was dialed for them.
33    Waiters,
34    /// Dialed to (re-)establish `h2_min_conns_per_origin`.
35    Min,
36    /// A connection with no streams for `idle_timeout` was closed.
37    Idle,
38    /// The origin was underused and one connection was drained and closed.
39    Underused,
40    /// A connection reached `max_connection_lifetime` and was retired.
41    Expired,
42    /// A connection was dialed to replace one past `max_connection_lifetime`.
43    Replace,
44}
45
46impl ScaleReason {
47    /// Stable lowercase name.
48    #[must_use]
49    pub const fn as_str(self) -> &'static str {
50        match self {
51            Self::Saturated => "saturated",
52            Self::Waiters => "waiters",
53            Self::Min => "min",
54            Self::Idle => "idle",
55            Self::Underused => "underused",
56            Self::Expired => "expired",
57            Self::Replace => "replace",
58        }
59    }
60}
61
62/// Instrumentation hooks. All methods default to no-ops; `matier-otel` implements them.
63/// Called on hot paths: implementations must not block or allocate per call where avoidable.
64#[allow(unused_variables, reason = "default no-op bodies")]
65pub trait Observer: Send + Sync + 'static {
66    /// Callers skip timestamping when this is false.
67    fn enabled(&self) -> bool {
68        false
69    }
70    /// Pool checkout + stream-slot wait.
71    fn request_queued(&self, o: &OriginKey, wait: Duration) {}
72    /// H2: enqueue to HEADERS written.
73    fn request_dispatched(&self, o: &OriginKey, delay: Duration) {}
74    fn connect_phase(&self, o: &OriginKey, phase: ConnectPhase, d: Duration, ok: bool) {}
75    fn connection_opened(&self, o: &OriginKey, p: Protocol) {}
76    fn connection_closed(&self, o: &OriginKey, p: Protocol, lifetime: Duration) {}
77    fn write_batch(&self, o: &OriginKey, bytes: usize, iovecs: usize) {}
78    fn bytes_read(&self, o: &OriginKey, n: usize) {}
79    fn actor_tick(&self, o: &OriginKey, busy: Duration, queue_depth: usize) {}
80    fn flow_control_stall(&self, o: &OriginKey, d: Duration) {}
81    fn h2_goaway(&self, o: &OriginKey, code: u32) {}
82    fn h2_rst_stream(&self, o: &OriginKey, code: u32, sent: bool) {}
83    fn pool_waiters(&self, o: &OriginKey, n: usize) {}
84    /// The pool changed the HTTP/2 connection count of `o`; `conns` is the new number of live connections.
85    /// Rare (at most a few per second); called from pool tasks, never from the request hot path.
86    fn pool_scaled(&self, o: &OriginKey, conns: usize, reason: ScaleReason) {}
87}
88
89/// The default observer: does nothing, `enabled()` is false.
90#[derive(Clone, Copy, Debug, Default)]
91pub struct NoopObserver;
92
93impl Observer for NoopObserver {}