Skip to main content

clm_rust_core/layer2/
observability.rs

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