tower_http_cache/
logging.rs

1//! ML-ready structured logging for cache operations.
2//!
3//! This module provides comprehensive structured logging suitable for
4//! machine learning training and analysis. All cache operations emit
5//! JSON-formatted logs with rich metadata for correlation and analysis.
6
7#[cfg(feature = "serde")]
8use crate::request_id::RequestId;
9#[cfg(feature = "serde")]
10use http::{Method, StatusCode, Uri, Version};
11#[cfg(feature = "serde")]
12use serde::{Deserialize, Serialize};
13#[cfg(feature = "serde")]
14use serde_json::json;
15use sha2::{Digest, Sha256};
16#[cfg(feature = "serde")]
17use std::time::{Duration, SystemTime};
18
19/// Configuration for ML-ready structured logging.
20#[derive(Debug, Clone)]
21pub struct MLLoggingConfig {
22    /// Enable ML-ready structured logging
23    pub enabled: bool,
24
25    /// Sample rate (1.0 = all requests, 0.1 = 10%)
26    pub sample_rate: f64,
27
28    /// Hash cache keys for privacy (recommended for production)
29    pub hash_keys: bool,
30
31    /// Target for structured logs (defaults to "tower_http_cache::ml")
32    pub target: String,
33}
34
35impl Default for MLLoggingConfig {
36    fn default() -> Self {
37        Self {
38            enabled: false,
39            sample_rate: 1.0,
40            hash_keys: true,
41            target: "tower_http_cache::ml".to_string(),
42        }
43    }
44}
45
46impl MLLoggingConfig {
47    /// Creates a new ML logging configuration with default settings.
48    pub fn new() -> Self {
49        Self::default()
50    }
51
52    /// Enables ML logging.
53    pub fn with_enabled(mut self, enabled: bool) -> Self {
54        self.enabled = enabled;
55        self
56    }
57
58    /// Sets the sample rate (0.0 to 1.0).
59    pub fn with_sample_rate(mut self, rate: f64) -> Self {
60        self.sample_rate = rate.clamp(0.0, 1.0);
61        self
62    }
63
64    /// Enables or disables key hashing.
65    pub fn with_hash_keys(mut self, hash: bool) -> Self {
66        self.hash_keys = hash;
67        self
68    }
69
70    /// Sets a custom logging target.
71    pub fn with_target(mut self, target: impl Into<String>) -> Self {
72        self.target = target.into();
73        self
74    }
75
76    /// Checks if this request should be logged based on sampling rate.
77    pub fn should_sample(&self) -> bool {
78        if !self.enabled {
79            return false;
80        }
81        if self.sample_rate >= 1.0 {
82            return true;
83        }
84        use std::collections::hash_map::RandomState;
85        use std::hash::BuildHasher;
86        let hasher = RandomState::new();
87
88        let random = (hasher.hash_one(std::time::SystemTime::now()) as f64) / (u64::MAX as f64);
89        random < self.sample_rate
90    }
91}
92
93/// Types of cache events that can be logged.
94#[derive(Debug, Clone)]
95#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
96#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
97pub enum CacheEventType {
98    /// Cache lookup hit (fresh entry)
99    Hit,
100    /// Cache lookup miss
101    Miss,
102    /// Stale entry served
103    StaleHit,
104    /// Cache entry stored
105    Store,
106    /// Cache entry invalidated
107    Invalidate,
108    /// Tag-based invalidation
109    TagInvalidate,
110    /// Multi-tier cache promotion
111    TierPromote,
112    /// Admin API access
113    AdminAccess,
114}
115
116/// Structured cache event for ML training.
117/// Structured cache event, emitted as JSON.
118///
119/// Requires the `serde` feature: the `metadata` field is a
120/// [`serde_json::Value`] and the payload is emitted as JSON.
121#[cfg(feature = "serde")]
122#[derive(Debug, Clone)]
123pub struct CacheEvent {
124    /// Timestamp of the event
125    pub timestamp: SystemTime,
126
127    /// Type of cache event
128    pub event_type: CacheEventType,
129
130    /// Request ID for correlation
131    pub request_id: RequestId,
132
133    /// Cache key (may be hashed)
134    pub key: String,
135
136    /// Request method
137    pub method: Option<Method>,
138
139    /// Request URI
140    pub uri: Option<Uri>,
141
142    /// HTTP version
143    pub version: Option<Version>,
144
145    /// Response status code
146    pub status: Option<StatusCode>,
147
148    /// Whether this was a cache hit
149    pub hit: bool,
150
151    /// Operation latency in microseconds
152    pub latency_us: Option<u64>,
153
154    /// Response size in bytes
155    pub size_bytes: Option<usize>,
156
157    /// TTL in seconds
158    pub ttl_seconds: Option<u64>,
159
160    /// Cache tags associated with this entry
161    pub tags: Option<Vec<String>>,
162
163    /// Tier information (l1, l2, or None)
164    pub tier: Option<String>,
165
166    /// Whether entry was promoted between tiers
167    pub promoted: bool,
168
169    /// Additional metadata
170    pub metadata: serde_json::Value,
171}
172
173#[cfg(feature = "serde")]
174impl CacheEvent {
175    /// Creates a new cache event.
176    pub fn new(event_type: CacheEventType, request_id: RequestId, key: String) -> Self {
177        Self {
178            timestamp: SystemTime::now(),
179            event_type,
180            request_id,
181            key,
182            method: None,
183            uri: None,
184            version: None,
185            status: None,
186            hit: false,
187            latency_us: None,
188            size_bytes: None,
189            ttl_seconds: None,
190            tags: None,
191            tier: None,
192            promoted: false,
193            metadata: json!({}),
194        }
195    }
196
197    /// Sets the HTTP method.
198    pub fn with_method(mut self, method: Method) -> Self {
199        self.method = Some(method);
200        self
201    }
202
203    /// Sets the request URI.
204    pub fn with_uri(mut self, uri: Uri) -> Self {
205        self.uri = Some(uri);
206        self
207    }
208
209    /// Sets the HTTP version.
210    pub fn with_version(mut self, version: Version) -> Self {
211        self.version = Some(version);
212        self
213    }
214
215    /// Sets the response status.
216    pub fn with_status(mut self, status: StatusCode) -> Self {
217        self.status = Some(status);
218        self
219    }
220
221    /// Sets whether this was a cache hit.
222    pub fn with_hit(mut self, hit: bool) -> Self {
223        self.hit = hit;
224        self
225    }
226
227    /// Sets the operation latency.
228    pub fn with_latency(mut self, latency: Duration) -> Self {
229        self.latency_us = Some(latency.as_micros() as u64);
230        self
231    }
232
233    /// Sets the response size.
234    pub fn with_size(mut self, size: usize) -> Self {
235        self.size_bytes = Some(size);
236        self
237    }
238
239    /// Sets the TTL.
240    pub fn with_ttl(mut self, ttl: Duration) -> Self {
241        self.ttl_seconds = Some(ttl.as_secs());
242        self
243    }
244
245    /// Sets the cache tags.
246    pub fn with_tags(mut self, tags: Vec<String>) -> Self {
247        self.tags = Some(tags);
248        self
249    }
250
251    /// Sets the tier information.
252    pub fn with_tier(mut self, tier: impl Into<String>) -> Self {
253        self.tier = Some(tier.into());
254        self
255    }
256
257    /// Sets whether the entry was promoted.
258    pub fn with_promoted(mut self, promoted: bool) -> Self {
259        self.promoted = promoted;
260        self
261    }
262
263    /// Adds custom metadata.
264    pub fn with_metadata(mut self, metadata: serde_json::Value) -> Self {
265        self.metadata = metadata;
266        self
267    }
268
269    /// Logs this event using the provided configuration.
270    pub fn log(&self, config: &MLLoggingConfig) {
271        if !config.should_sample() {
272            return;
273        }
274
275        let key = if config.hash_keys {
276            hash_key(&self.key)
277        } else {
278            self.key.clone()
279        };
280
281        let timestamp = self
282            .timestamp
283            .duration_since(SystemTime::UNIX_EPOCH)
284            .unwrap_or_default();
285
286        let log_data = json!({
287            "timestamp": format!("{}.{:03}Z",
288                chrono::DateTime::<chrono::Utc>::from(self.timestamp)
289                    .format("%Y-%m-%dT%H:%M:%S"),
290                timestamp.subsec_millis()
291            ),
292            "level": "info",
293            "event": format!("{:?}", self.event_type).to_lowercase(),
294            "request_id": self.request_id.as_str(),
295            "key": key,
296            "method": self.method.as_ref().map(|m| m.as_str()),
297            "uri": self.uri.as_ref().map(|u| u.to_string()),
298            "version": self.version.as_ref().map(|v| format!("{:?}", v)),
299            "status": self.status.as_ref().map(|s| s.as_u16()),
300            "hit": self.hit,
301            "latency_us": self.latency_us,
302            "size_bytes": self.size_bytes,
303            "ttl_seconds": self.ttl_seconds,
304            "tags": self.tags,
305            "tier": self.tier,
306            "promoted": self.promoted,
307            "metadata": self.metadata,
308        });
309
310        #[cfg(feature = "tracing")]
311        {
312            // Use fixed target for tracing, but include the configured target in the log data
313            tracing::info!(
314                target: "tower_http_cache::ml",
315                event = %log_data
316            );
317        }
318
319        #[cfg(not(feature = "tracing"))]
320        {
321            // Fallback to println for non-tracing builds
322            let _ = config; // suppress warning
323            println!("{}", log_data);
324        }
325    }
326}
327
328/// Hashes a cache key using SHA-256 for privacy.
329pub fn hash_key(key: &str) -> String {
330    let mut hasher = Sha256::new();
331    hasher.update(key.as_bytes());
332    let result = hasher.finalize();
333    hex::encode(result)
334}
335
336/// Helper to log a simple cache operation.
337#[cfg(feature = "serde")]
338pub fn log_cache_operation(
339    config: &MLLoggingConfig,
340    event_type: CacheEventType,
341    request_id: RequestId,
342    key: String,
343) {
344    if !config.enabled {
345        return;
346    }
347
348    let event = CacheEvent::new(event_type, request_id, key);
349    event.log(config);
350}
351
352#[cfg(test)]
353mod tests {
354    use super::*;
355
356    #[test]
357    fn ml_logging_config_default() {
358        let config = MLLoggingConfig::default();
359        assert!(!config.enabled);
360        assert_eq!(config.sample_rate, 1.0);
361        assert!(config.hash_keys);
362    }
363
364    #[test]
365    fn ml_logging_config_builder() {
366        let config = MLLoggingConfig::new()
367            .with_enabled(true)
368            .with_sample_rate(0.5)
369            .with_hash_keys(false)
370            .with_target("custom::target");
371
372        assert!(config.enabled);
373        assert_eq!(config.sample_rate, 0.5);
374        assert!(!config.hash_keys);
375        assert_eq!(config.target, "custom::target");
376    }
377
378    #[test]
379    fn sample_rate_clamped() {
380        let config = MLLoggingConfig::new().with_sample_rate(1.5);
381        assert_eq!(config.sample_rate, 1.0);
382
383        let config = MLLoggingConfig::new().with_sample_rate(-0.5);
384        assert_eq!(config.sample_rate, 0.0);
385    }
386
387    #[test]
388    fn should_sample_when_disabled() {
389        let config = MLLoggingConfig::new().with_enabled(false);
390        assert!(!config.should_sample());
391    }
392
393    #[test]
394    fn should_sample_when_rate_is_one() {
395        let config = MLLoggingConfig::new()
396            .with_enabled(true)
397            .with_sample_rate(1.0);
398        assert!(config.should_sample());
399    }
400
401    #[test]
402    fn hash_key_consistent() {
403        let key = "/api/users/123";
404        let hash1 = hash_key(key);
405        let hash2 = hash_key(key);
406        assert_eq!(hash1, hash2);
407        assert_ne!(hash1, key);
408        assert_eq!(hash1.len(), 64); // SHA-256 produces 64 hex chars
409    }
410
411    #[cfg(feature = "serde")]
412    #[test]
413    fn cache_event_builder() {
414        let request_id = RequestId::new();
415        let event = CacheEvent::new(CacheEventType::Hit, request_id.clone(), "/test".to_string())
416            .with_method(Method::GET)
417            .with_status(StatusCode::OK)
418            .with_hit(true)
419            .with_latency(Duration::from_micros(150))
420            .with_size(1024)
421            .with_ttl(Duration::from_secs(300))
422            .with_tags(vec!["user:123".to_string()])
423            .with_tier("l1")
424            .with_promoted(false);
425
426        assert_eq!(event.method, Some(Method::GET));
427        assert_eq!(event.status, Some(StatusCode::OK));
428        assert!(event.hit);
429        assert_eq!(event.latency_us, Some(150));
430        assert_eq!(event.size_bytes, Some(1024));
431        assert_eq!(event.ttl_seconds, Some(300));
432        assert_eq!(event.tags, Some(vec!["user:123".to_string()]));
433        assert_eq!(event.tier, Some("l1".to_string()));
434        assert!(!event.promoted);
435    }
436
437    #[cfg(feature = "serde")]
438    #[test]
439    fn cache_event_log_disabled() {
440        let config = MLLoggingConfig::new().with_enabled(false);
441        let request_id = RequestId::new();
442        let event = CacheEvent::new(CacheEventType::Hit, request_id, "/test".to_string());
443
444        // Should not panic when logging is disabled
445        event.log(&config);
446    }
447
448    #[cfg(feature = "serde")]
449    #[test]
450    fn cache_event_log_with_hashing() {
451        let config = MLLoggingConfig::new()
452            .with_enabled(true)
453            .with_hash_keys(true);
454        let request_id = RequestId::new();
455        let event = CacheEvent::new(CacheEventType::Hit, request_id, "/api/secret".to_string());
456
457        // Should not panic when logging with hashing
458        event.log(&config);
459    }
460
461    #[cfg(feature = "serde")]
462    #[test]
463    fn log_cache_operation_helper() {
464        let config = MLLoggingConfig::new().with_enabled(true);
465        let request_id = RequestId::new();
466
467        // Should not panic
468        log_cache_operation(
469            &config,
470            CacheEventType::Miss,
471            request_id,
472            "/test".to_string(),
473        );
474    }
475}
tower_http_cache/logging.rs

tower_http_cache/
logging.rs
