gemini_genai_rs/telemetry/
logging.rs

1//! Structured logging helpers.
2//!
3//! All log events carry consistent fields (session_id, phase) for correlation.
4//! Feature-gated behind `tracing-support`.
5
6/// Log a session lifecycle event.
7#[cfg(feature = "tracing-support")]
8pub fn log_session_event(session_id: &str, phase: &str, event: &str) {
9    tracing::info!(
10        session_id = session_id,
11        phase = phase,
12        event = event,
13        "Session event"
14    );
15}
16
17/// Log a tool call dispatch.
18#[cfg(feature = "tracing-support")]
19pub fn log_tool_call(session_id: &str, function_name: &str, call_count: usize) {
20    tracing::info!(
21        session_id = session_id,
22        event = "tool_call_received",
23        function_name = function_name,
24        function_count = call_count,
25        "Model requested function calls"
26    );
27}
28
29/// Log a WebSocket error (warn level).
30#[cfg(feature = "tracing-support")]
31pub fn log_ws_error(session_id: &str, error: &str) {
32    tracing::warn!(
33        session_id = session_id,
34        event = "websocket_error",
35        error = error,
36        "WebSocket error"
37    );
38}
39
40/// Log a jitter buffer underrun (warn level).
41#[cfg(feature = "tracing-support")]
42pub fn log_jitter_underrun(session_id: &str, depth_ms: f64) {
43    tracing::warn!(
44        session_id = session_id,
45        event = "jitter_underrun",
46        depth_ms = depth_ms,
47        "Jitter buffer underrun"
48    );
49}
50
51/// Log a reconnection attempt (warn level).
52#[cfg(feature = "tracing-support")]
53pub fn log_reconnection(session_id: &str, attempt: u32, delay_ms: u64) {
54    tracing::warn!(
55        session_id = session_id,
56        event = "reconnection",
57        attempt = attempt,
58        delay_ms = delay_ms,
59        "Reconnection attempt"
60    );
61}
62
63/// Log VAD state change (debug level).
64#[cfg(feature = "tracing-support")]
65pub fn log_vad_event(session_id: &str, event: &str) {
66    tracing::debug!(
67        session_id = session_id,
68        event = "vad_state_change",
69        vad_event = event,
70        "VAD event"
71    );
72}
73
74/// Log an HTTP request (info level).
75#[cfg(feature = "tracing-support")]
76pub fn log_http_request(method: &str, url: &str) {
77    tracing::info!(
78        event = "http_request",
79        http.method = method,
80        http.url = url,
81        "HTTP request"
82    );
83}
84
85/// Log an HTTP response (info level).
86#[cfg(feature = "tracing-support")]
87pub fn log_http_response(status: u16, duration_ms: f64) {
88    tracing::info!(
89        event = "http_response",
90        http.status = status,
91        duration_ms = duration_ms,
92        "HTTP response"
93    );
94}
95
96/// Log an HTTP retry attempt (warn level).
97#[cfg(feature = "tracing-support")]
98pub fn log_http_retry(url: &str, attempt: u32, delay_ms: u64) {
99    tracing::warn!(
100        event = "http_retry",
101        http.url = url,
102        attempt = attempt,
103        delay_ms = delay_ms,
104        "HTTP retry"
105    );
106}
107
108// No-op stubs when tracing is disabled.
109#[cfg(not(feature = "tracing-support"))]
110pub fn log_session_event(_: &str, _: &str, _: &str) {}
111#[cfg(not(feature = "tracing-support"))]
112pub fn log_tool_call(_: &str, _: &str, _: usize) {}
113#[cfg(not(feature = "tracing-support"))]
114pub fn log_ws_error(_: &str, _: &str) {}
115#[cfg(not(feature = "tracing-support"))]
116pub fn log_jitter_underrun(_: &str, _: f64) {}
117#[cfg(not(feature = "tracing-support"))]
118pub fn log_reconnection(_: &str, _: u32, _: u64) {}
119#[cfg(not(feature = "tracing-support"))]
120pub fn log_vad_event(_: &str, _: &str) {}
121#[cfg(not(feature = "tracing-support"))]
122pub fn log_http_request(_: &str, _: &str) {}
123#[cfg(not(feature = "tracing-support"))]
124pub fn log_http_response(_: u16, _: f64) {}
125#[cfg(not(feature = "tracing-support"))]
126pub fn log_http_retry(_: &str, _: u32, _: u64) {}
127
128#[cfg(test)]
129mod tests {
130    use super::*;
131
132    #[test]
133    fn noop_log_functions_compile() {
134        // All log functions should compile and not panic as no-ops.
135        log_session_event("sess-1", "greeting", "connected");
136        log_tool_call("sess-1", "get_weather", 1);
137        log_ws_error("sess-1", "connection reset");
138        log_jitter_underrun("sess-1", 50.0);
139        log_reconnection("sess-1", 1, 1000);
140        log_vad_event("sess-1", "speech_start");
141        log_http_request("GET", "https://example.com");
142        log_http_response(200, 42.5);
143        log_http_retry("https://example.com", 2, 2000);
144    }
145}
gemini_genai_rs/telemetry/logging.rs

gemini_genai_rs/telemetry/
logging.rs
