photon-telemetry 0.1.1

Photon OpsLog telemetry port
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

//! Operations telemetry port for Photon.
//!
//! Hosts install a process-wide [`OpsLog`] via [`install_ops_log`] or
//! [`PhotonBuilder::ops_log`](https://docs.rs/uf-photon/latest/photon/struct.PhotonBuilder.html#method.ops_log).
//! Backend instrumentation (publish counters, DLQ rows, checkpoint failures) calls [`ops_log`].
//!
//! ## Entry points
//!
//! - [`OpsLog`] — counter / gauge / event trait
//! - [`install_ops_log`] / [`ops_log`] / [`ops_log_from_env`] — process-wide adapter
//! - [`ConsoleOpsLog`] / [`NoOpsLog`] — shipped adapters
//!
//! Runnable: `cargo run -p uf-photon --example telemetry_ops_log --features runtime,mem`.

mod console;
mod global;
mod noop;

#[cfg(feature = "recording")]
mod recording;

pub use console::ConsoleOpsLog;
pub use global::{install_ops_log, ops_log, ops_log_from_env};
pub use noop::NoOpsLog;

#[cfg(feature = "recording")]
pub use recording::{RecordedCounter, RecordedEvent, RecordedGauge, RecordingOpsLog};

/// Structured ops metrics/events for publish, drain, DLQ, checkpoints.
///
/// Install before or during [`PhotonBuilder::build`](https://docs.rs/uf-photon/latest/photon/struct.PhotonBuilder.html#method.build)
/// via [`PhotonBuilder::ops_log`](https://docs.rs/uf-photon/latest/photon/struct.PhotonBuilder.html#method.ops_log)
/// (or [`install_ops_log`]). Photon calls this trait from backend instrumentation — it is not the
/// application event bus.
///
/// # Example
///
/// ```rust,ignore
/// use photon_runtime::Photon;
/// use photon_telemetry::ConsoleOpsLog;
///
/// let _photon = Photon::builder()
///     .ops_log(ConsoleOpsLog)
///     .auto_registry()
///     .build()?;
/// ```
pub trait OpsLog: Send + Sync {
    /// Increment a counter with optional labels.
    fn record_counter(&self, name: &str, labels: &[(&str, &str)], value: f64);

    /// Set a gauge with optional labels.
    fn record_gauge(&self, name: &str, labels: &[(&str, &str)], value: f64);

    /// Emit a structured diagnostic event.
    fn log_event(&self, name: &str, payload: &serde_json::Value);
}

#[cfg(test)]
mod tests {
    use super::{ConsoleOpsLog, NoOpsLog, OpsLog};

    #[test]
    fn noop_ops_log_is_silent() {
        let log = NoOpsLog;
        log.record_counter("c", &[], 1.0);
        log.record_gauge("g", &[], 2.0);
        log.log_event("e", &serde_json::json!({}));
    }

    #[test]
    fn console_ops_log_does_not_panic() {
        let log = ConsoleOpsLog;
        log.record_counter("photon_publishes", &[("topic", "t")], 1.0);
    }
}