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