Skip to main content

clm_rust_core/
observability.rs

1use rusqlite::Connection;
2use serde::{Deserialize, Serialize};
3use std::path::PathBuf;
4use rand::RngCore;
5
6#[derive(Debug, Serialize, Deserialize, Clone)]
7pub struct ObservabilityConfigRecord {
8    pub tempo_endpoint: String,
9    pub loki_endpoint: String,
10    pub mimir_endpoint: String,
11    pub sampling_rate: f64,
12    pub handle: String,
13    pub content_hash: String,
14}
15
16#[derive(Debug, Serialize, Deserialize, Clone)]
17pub struct TraceSpanRecord {
18    pub trace_id: String,
19    pub span_id: String,
20    pub parent_span_id: Option<String>,
21    pub pcard_handle: String,
22    pub vcard_hash: String,
23    pub duration_ms: u64,
24    pub timestamp: String,
25    pub handle: String,
26    pub content_hash: String,
27}
28
29#[derive(Debug, Serialize, Deserialize, Clone)]
30pub struct MetricRecord {
31    pub metric_name: String,
32    pub value: f64,
33    pub labels: serde_json::Value,
34    pub timestamp: String,
35    pub handle: String,
36    pub content_hash: String,
37}
38
39#[derive(Debug, Serialize, Deserialize, Clone)]
40pub struct StructuredLogRecord {
41    pub log_id: String,
42    pub trace_id: String,
43    pub level: String,
44    pub vcard_hash: String,
45    pub eoa_did: String,
46    pub message: String,
47    pub timestamp: String,
48    pub handle: String,
49    pub content_hash: String,
50}
51
52fn resolve_db_path(db_name_or_path: &str, clm_root: Option<&str>) -> PathBuf {
53    if db_name_or_path.contains('/') || db_name_or_path.contains('\\') {
54        PathBuf::from(db_name_or_path)
55    } else {
56        let root = clm_root.map(PathBuf::from).unwrap_or_else(|| {
57            std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
58        });
59        root.join("data").join("execution_logs").join(db_name_or_path)
60    }
61}
62
63fn init_db_tables(conn: &Connection) -> Result<(), String> {
64    conn.execute(
65        "CREATE TABLE IF NOT EXISTS card (
66            hash TEXT PRIMARY KEY,
67            content TEXT NOT NULL,
68            g_time TEXT
69        );",
70        [],
71    ).map_err(|e| e.to_string())?;
72
73    conn.execute(
74        "CREATE TABLE IF NOT EXISTS handle_registry (
75            handle TEXT PRIMARY KEY,
76            hash TEXT NOT NULL
77        );",
78        [],
79    ).map_err(|e| e.to_string())?;
80
81    Ok(())
82}
83
84fn generate_sha256(content: &str) -> String {
85    use sha2::{Digest, Sha256};
86    let mut hasher = Sha256::new();
87    hasher.update(content.as_bytes());
88    hex::encode(hasher.finalize())
89}
90
91/// Configures observability telemetry endpoints and stores configuration MCard (`mcard:observability/config`).
92pub fn configure_observability(
93    db_name_or_path: &str,
94    clm_root: Option<&str>,
95    tempo_endpoint: &str,
96    loki_endpoint: &str,
97    mimir_endpoint: &str,
98    sampling_rate: Option<f64>,
99) -> Result<ObservabilityConfigRecord, String> {
100    let db_path = resolve_db_path(db_name_or_path, clm_root);
101    if let Some(parent) = db_path.parent() {
102        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
103    }
104    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
105    init_db_tables(&conn)?;
106
107    let rate = sampling_rate.unwrap_or(1.0);
108    let handle = "mcard:observability/config".to_string();
109
110    let json_val = serde_json::json!({
111        "type": "observability_config",
112        "tempo_endpoint": tempo_endpoint,
113        "loki_endpoint": loki_endpoint,
114        "mimir_endpoint": mimir_endpoint,
115        "sampling_rate": rate
116    });
117
118    let content_json = json_val.to_string();
119    let content_hash = generate_sha256(&content_json);
120
121    conn.execute(
122        "INSERT INTO card (hash, content) VALUES (?1, ?2) ON CONFLICT(hash) DO UPDATE SET content=excluded.content;",
123        rusqlite::params![content_hash, content_json],
124    ).map_err(|e| e.to_string())?;
125
126    conn.execute(
127        "INSERT INTO handle_registry (handle, hash) VALUES (?1, ?2) ON CONFLICT(handle) DO UPDATE SET hash=excluded.hash;",
128        rusqlite::params![handle, content_hash],
129    ).map_err(|e| e.to_string())?;
130
131    Ok(ObservabilityConfigRecord {
132        tempo_endpoint: tempo_endpoint.to_string(),
133        loki_endpoint: loki_endpoint.to_string(),
134        mimir_endpoint: mimir_endpoint.to_string(),
135        sampling_rate: rate,
136        handle,
137        content_hash,
138    })
139}
140
141/// Emits an OpenTelemetry trace span and stores MCard (`mcard:observability/trace/{trace_id}`).
142pub fn emit_trace_span(
143    db_name_or_path: &str,
144    clm_root: Option<&str>,
145    trace_id: &str,
146    span_id: &str,
147    parent_span_id: Option<&str>,
148    pcard_handle: &str,
149    vcard_hash: &str,
150    duration_ms: u64,
151) -> Result<TraceSpanRecord, String> {
152    let db_path = resolve_db_path(db_name_or_path, clm_root);
153    if let Some(parent) = db_path.parent() {
154        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
155    }
156    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
157    init_db_tables(&conn)?;
158
159    let timestamp = chrono::Utc::now().to_rfc3339();
160    let handle = format!("mcard:observability/trace/{}", trace_id);
161
162    let json_val = serde_json::json!({
163        "type": "trace_span",
164        "trace_id": trace_id,
165        "span_id": span_id,
166        "parent_span_id": parent_span_id,
167        "pcard_handle": pcard_handle,
168        "vcard_hash": vcard_hash,
169        "duration_ms": duration_ms,
170        "timestamp": timestamp
171    });
172
173    let content_json = json_val.to_string();
174    let content_hash = generate_sha256(&content_json);
175
176    conn.execute(
177        "INSERT INTO card (hash, content) VALUES (?1, ?2) ON CONFLICT(hash) DO UPDATE SET content=excluded.content;",
178        rusqlite::params![content_hash, content_json],
179    ).map_err(|e| e.to_string())?;
180
181    conn.execute(
182        "INSERT INTO handle_registry (handle, hash) VALUES (?1, ?2) ON CONFLICT(handle) DO UPDATE SET hash=excluded.hash;",
183        rusqlite::params![handle, content_hash],
184    ).map_err(|e| e.to_string())?;
185
186    Ok(TraceSpanRecord {
187        trace_id: trace_id.to_string(),
188        span_id: span_id.to_string(),
189        parent_span_id: parent_span_id.map(|s| s.to_string()),
190        pcard_handle: pcard_handle.to_string(),
191        vcard_hash: vcard_hash.to_string(),
192        duration_ms,
193        timestamp,
194        handle,
195        content_hash,
196    })
197}
198
199/// Records a metric event and stores MCard (`mcard:observability/metric/{metric_name}`).
200pub fn record_metric(
201    db_name_or_path: &str,
202    clm_root: Option<&str>,
203    metric_name: &str,
204    value: f64,
205    labels_json: Option<&str>,
206) -> Result<MetricRecord, String> {
207    let db_path = resolve_db_path(db_name_or_path, clm_root);
208    if let Some(parent) = db_path.parent() {
209        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
210    }
211    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
212    init_db_tables(&conn)?;
213
214    let timestamp = chrono::Utc::now().to_rfc3339();
215    let handle = format!("mcard:observability/metric/{}", metric_name);
216    let labels: serde_json::Value = match labels_json {
217        Some(s) => serde_json::from_str(s).unwrap_or_else(|_| serde_json::json!({})),
218        None => serde_json::json!({}),
219    };
220
221    let json_val = serde_json::json!({
222        "type": "metric_event",
223        "metric_name": metric_name,
224        "value": value,
225        "labels": labels,
226        "timestamp": timestamp
227    });
228
229    let content_json = json_val.to_string();
230    let content_hash = generate_sha256(&content_json);
231
232    conn.execute(
233        "INSERT INTO card (hash, content) VALUES (?1, ?2) ON CONFLICT(hash) DO UPDATE SET content=excluded.content;",
234        rusqlite::params![content_hash, content_json],
235    ).map_err(|e| e.to_string())?;
236
237    conn.execute(
238        "INSERT INTO handle_registry (handle, hash) VALUES (?1, ?2) ON CONFLICT(handle) DO UPDATE SET hash=excluded.hash;",
239        rusqlite::params![handle, content_hash],
240    ).map_err(|e| e.to_string())?;
241
242    Ok(MetricRecord {
243        metric_name: metric_name.to_string(),
244        value,
245        labels,
246        timestamp,
247        handle,
248        content_hash,
249    })
250}
251
252/// Emits a Loki-compatible structured log entry and stores MCard (`mcard:observability/log/{log_id}`).
253pub fn emit_structured_log(
254    db_name_or_path: &str,
255    clm_root: Option<&str>,
256    trace_id: &str,
257    level: &str,
258    vcard_hash: &str,
259    eoa_did: &str,
260    message: &str,
261) -> Result<StructuredLogRecord, String> {
262    let db_path = resolve_db_path(db_name_or_path, clm_root);
263    if let Some(parent) = db_path.parent() {
264        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
265    }
266    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
267    init_db_tables(&conn)?;
268
269    let mut log_bytes = [0u8; 8];
270    rand::thread_rng().fill_bytes(&mut log_bytes);
271    let log_id = format!("log_{}", hex::encode(log_bytes));
272    let handle = format!("mcard:observability/log/{}", log_id);
273    let timestamp = chrono::Utc::now().to_rfc3339();
274
275    let json_val = serde_json::json!({
276        "type": "structured_log",
277        "log_id": log_id,
278        "trace_id": trace_id,
279        "level": level,
280        "vcard_hash": vcard_hash,
281        "eoa_did": eoa_did,
282        "message": message,
283        "timestamp": timestamp
284    });
285
286    let content_json = json_val.to_string();
287    let content_hash = generate_sha256(&content_json);
288
289    conn.execute(
290        "INSERT INTO card (hash, content) VALUES (?1, ?2) ON CONFLICT(hash) DO UPDATE SET content=excluded.content;",
291        rusqlite::params![content_hash, content_json],
292    ).map_err(|e| e.to_string())?;
293
294    conn.execute(
295        "INSERT INTO handle_registry (handle, hash) VALUES (?1, ?2) ON CONFLICT(handle) DO UPDATE SET hash=excluded.hash;",
296        rusqlite::params![handle, content_hash],
297    ).map_err(|e| e.to_string())?;
298
299    Ok(StructuredLogRecord {
300        log_id,
301        trace_id: trace_id.to_string(),
302        level: level.to_string(),
303        vcard_hash: vcard_hash.to_string(),
304        eoa_did: eoa_did.to_string(),
305        message: message.to_string(),
306        timestamp,
307        handle,
308        content_hash,
309    })
310}
311
312/// Retrieves trace span MCard content by `trace_id`.
313pub fn get_trace(
314    db_name_or_path: &str,
315    clm_root: Option<&str>,
316    trace_id: &str,
317) -> Result<TraceSpanRecord, String> {
318    let db_path = resolve_db_path(db_name_or_path, clm_root);
319    if !db_path.exists() {
320        return Err(format!("Database not found for trace {}", trace_id));
321    }
322    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
323    let handle = format!("mcard:observability/trace/{}", trace_id);
324
325    let (content, content_hash): (String, String) = conn.query_row(
326        "SELECT c.content, c.hash FROM card c JOIN handle_registry h ON c.hash = h.hash WHERE h.handle = ?1;",
327        rusqlite::params![handle],
328        |row| {
329            let c: String = row.get(0)?;
330            let h: String = row.get(1)?;
331            Ok((c, h))
332        },
333    ).map_err(|_| format!("Trace span {} not found", trace_id))?;
334
335    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
336    Ok(TraceSpanRecord {
337        trace_id: v.get("trace_id").and_then(|x| x.as_str()).unwrap_or(trace_id).to_string(),
338        span_id: v.get("span_id").and_then(|x| x.as_str()).unwrap_or("").to_string(),
339        parent_span_id: v.get("parent_span_id").and_then(|x| x.as_str()).map(|x| x.to_string()),
340        pcard_handle: v.get("pcard_handle").and_then(|x| x.as_str()).unwrap_or("").to_string(),
341        vcard_hash: v.get("vcard_hash").and_then(|x| x.as_str()).unwrap_or("").to_string(),
342        duration_ms: v.get("duration_ms").and_then(|x| x.as_u64()).unwrap_or(0),
343        timestamp: v.get("timestamp").and_then(|x| x.as_str()).unwrap_or("").to_string(),
344        handle,
345        content_hash,
346    })
347}
348
349/// Retrieves metric MCard content by `metric_name`.
350pub fn get_metric(
351    db_name_or_path: &str,
352    clm_root: Option<&str>,
353    metric_name: &str,
354) -> Result<MetricRecord, String> {
355    let db_path = resolve_db_path(db_name_or_path, clm_root);
356    if !db_path.exists() {
357        return Err(format!("Database not found for metric {}", metric_name));
358    }
359    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
360    let handle = format!("mcard:observability/metric/{}", metric_name);
361
362    let (content, content_hash): (String, String) = conn.query_row(
363        "SELECT c.content, c.hash FROM card c JOIN handle_registry h ON c.hash = h.hash WHERE h.handle = ?1;",
364        rusqlite::params![handle],
365        |row| {
366            let c: String = row.get(0)?;
367            let h: String = row.get(1)?;
368            Ok((c, h))
369        },
370    ).map_err(|_| format!("Metric {} not found", metric_name))?;
371
372    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
373    Ok(MetricRecord {
374        metric_name: v.get("metric_name").and_then(|x| x.as_str()).unwrap_or(metric_name).to_string(),
375        value: v.get("value").and_then(|x| x.as_f64()).unwrap_or(0.0),
376        labels: v.get("labels").cloned().unwrap_or_else(|| serde_json::json!({})),
377        timestamp: v.get("timestamp").and_then(|x| x.as_str()).unwrap_or("").to_string(),
378        handle,
379        content_hash,
380    })
381}
382
383#[cfg(test)]
384mod tests {
385    use super::*;
386
387    #[test]
388    fn test_observability_pipeline() {
389        let db_path = "/tmp/test_observability.db";
390        let _ = std::fs::remove_file(db_path);
391
392        // 1. Configure observability
393        let cfg = configure_observability(db_path, None, "http://localhost:4317", "http://localhost:3100", "http://localhost:9009", Some(1.0)).unwrap();
394        assert_eq!(cfg.tempo_endpoint, "http://localhost:4317");
395
396        // 2. Emit trace span
397        let trace = emit_trace_span(db_path, None, "tr_001", "sp_001", None, "pcard:auth/verify", "0xhash123", 42).unwrap();
398        assert_eq!(trace.trace_id, "tr_001");
399
400        // 3. Query trace span
401        let fetched_trace = get_trace(db_path, None, "tr_001").unwrap();
402        assert_eq!(fetched_trace.duration_ms, 42);
403        assert_eq!(fetched_trace.vcard_hash, "0xhash123");
404
405        // 4. Record metric
406        let metric = record_metric(db_path, None, "pkc_auth_success_total", 1.0, Some(r#"{"provider":"zitadel"}"#)).unwrap();
407        assert_eq!(metric.metric_name, "pkc_auth_success_total");
408
409        // 5. Query metric
410        let fetched_metric = get_metric(db_path, None, "pkc_auth_success_total").unwrap();
411        assert_eq!(fetched_metric.value, 1.0);
412
413        // 6. Emit structured log
414        let log_rec = emit_structured_log(db_path, None, "tr_001", "INFO", "0xhash123", "did:key:z6MkAgent", "Auth challenge verified").unwrap();
415        assert_eq!(log_rec.level, "INFO");
416
417        let _ = std::fs::remove_file(db_path);
418    }
419}