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    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
140
141    let now = chrono::Utc::now().to_rfc3339();
142    conn.execute(
143        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
144         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
145        rusqlite::params![handle, content_hash, now],
146    ).map_err(|e| e.to_string())?;
147
148    Ok(ObservabilityConfigRecord {
149        tempo_endpoint: tempo_endpoint.to_string(),
150        loki_endpoint: loki_endpoint.to_string(),
151        mimir_endpoint: mimir_endpoint.to_string(),
152        sampling_rate: rate,
153        handle,
154        content_hash,
155    })
156}
157
158/// Emits an OpenTelemetry trace span and stores MCard (`mcard:observability/trace/{trace_id}`).
159pub fn emit_trace_span(
160    db_name_or_path: &str,
161    clm_root: Option<&str>,
162    trace_id: &str,
163    span_id: &str,
164    parent_span_id: Option<&str>,
165    pcard_handle: &str,
166    vcard_hash: &str,
167    duration_ms: u64,
168) -> Result<TraceSpanRecord, String> {
169    let db_path = resolve_db_path(db_name_or_path, clm_root);
170    if let Some(parent) = db_path.parent() {
171        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
172    }
173    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
174    init_db_tables(&conn)?;
175
176    let timestamp = chrono::Utc::now().to_rfc3339();
177    let handle = format!("{HANDLE_MCARD_OBSERVABILITY_TRACE}{}", trace_id);
178
179    let json_val = serde_json::json!({
180        "type": "trace_span",
181        "trace_id": trace_id,
182        "span_id": span_id,
183        "parent_span_id": parent_span_id,
184        "pcard_handle": pcard_handle,
185        "vcard_hash": vcard_hash,
186        "duration_ms": duration_ms,
187        "timestamp": timestamp
188    });
189
190    let content_json = json_val.to_string();
191    let content_hash = generate_sha256(&content_json);
192
193    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
194
195    conn.execute(
196        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
197         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
198        rusqlite::params![handle, content_hash, timestamp],
199    ).map_err(|e| e.to_string())?;
200
201    Ok(TraceSpanRecord {
202        trace_id: trace_id.to_string(),
203        span_id: span_id.to_string(),
204        parent_span_id: parent_span_id.map(|s| s.to_string()),
205        pcard_handle: pcard_handle.to_string(),
206        vcard_hash: vcard_hash.to_string(),
207        duration_ms,
208        timestamp,
209        handle,
210        content_hash,
211    })
212}
213
214/// Records a metric event and stores MCard (`mcard:observability/metric/{metric_name}`).
215pub fn record_metric(
216    db_name_or_path: &str,
217    clm_root: Option<&str>,
218    metric_name: &str,
219    value: f64,
220    labels_json: Option<&str>,
221) -> Result<MetricRecord, String> {
222    let db_path = resolve_db_path(db_name_or_path, clm_root);
223    if let Some(parent) = db_path.parent() {
224        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
225    }
226    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
227    init_db_tables(&conn)?;
228
229    let timestamp = chrono::Utc::now().to_rfc3339();
230    let handle = format!("{HANDLE_MCARD_OBSERVABILITY_METRIC}{}", metric_name);
231    let labels: serde_json::Value = match labels_json {
232        Some(s) => serde_json::from_str(s).unwrap_or_else(|_| serde_json::json!({})),
233        None => serde_json::json!({}),
234    };
235
236    let json_val = serde_json::json!({
237        "type": "metric_event",
238        "metric_name": metric_name,
239        "value": value,
240        "labels": labels,
241        "timestamp": timestamp
242    });
243
244    let content_json = json_val.to_string();
245    let content_hash = generate_sha256(&content_json);
246
247    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
248
249    conn.execute(
250        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
251         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
252        rusqlite::params![handle, content_hash, timestamp],
253    ).map_err(|e| e.to_string())?;
254
255    Ok(MetricRecord {
256        metric_name: metric_name.to_string(),
257        value,
258        labels,
259        timestamp,
260        handle,
261        content_hash,
262    })
263}
264
265/// Emits a Loki-compatible structured log entry and stores MCard (`mcard:observability/log/{log_id}`).
266pub fn emit_structured_log(
267    db_name_or_path: &str,
268    clm_root: Option<&str>,
269    trace_id: &str,
270    level: &str,
271    vcard_hash: &str,
272    eoa_did: &str,
273    message: &str,
274) -> Result<StructuredLogRecord, String> {
275    let db_path = resolve_db_path(db_name_or_path, clm_root);
276    if let Some(parent) = db_path.parent() {
277        std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
278    }
279    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
280    init_db_tables(&conn)?;
281
282    let mut log_bytes = [0u8; 8];
283    rand::thread_rng().fill_bytes(&mut log_bytes);
284    let log_id = format!("log_{}", hex::encode(log_bytes));
285    let handle = format!("{HANDLE_MCARD_OBSERVABILITY_LOG}{}", log_id);
286    let timestamp = chrono::Utc::now().to_rfc3339();
287
288    let json_val = serde_json::json!({
289        "type": "structured_log",
290        "log_id": log_id,
291        "trace_id": trace_id,
292        "level": level,
293        "vcard_hash": vcard_hash,
294        "eoa_did": eoa_did,
295        "message": message,
296        "timestamp": timestamp
297    });
298
299    let content_json = json_val.to_string();
300    let content_hash = generate_sha256(&content_json);
301
302    crate::layer2::record_store::insert_new_content(&conn, &content_hash, content_json.as_bytes(), crate::layer0::vocabulary::HASH_ALGORITHM_SHA256).map_err(|e| e.to_string())?;
303
304    conn.execute(
305        "INSERT INTO handle_registry (handle, current_hash, updated_at) VALUES (?1, ?2, ?3) \
306         ON CONFLICT(handle) DO UPDATE SET current_hash=excluded.current_hash, updated_at=excluded.updated_at;",
307        rusqlite::params![handle, content_hash, timestamp],
308    ).map_err(|e| e.to_string())?;
309
310    Ok(StructuredLogRecord {
311        log_id,
312        trace_id: trace_id.to_string(),
313        level: level.to_string(),
314        vcard_hash: vcard_hash.to_string(),
315        eoa_did: eoa_did.to_string(),
316        message: message.to_string(),
317        timestamp,
318        handle,
319        content_hash,
320    })
321}
322
323/// Retrieves trace span MCard content by `trace_id`.
324pub fn get_trace(
325    db_name_or_path: &str,
326    clm_root: Option<&str>,
327    trace_id: &str,
328) -> Result<TraceSpanRecord, String> {
329    let db_path = resolve_db_path(db_name_or_path, clm_root);
330    if !db_path.exists() {
331        return Err(format!("Database not found for trace {}", trace_id));
332    }
333    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
334    let handle = format!("{HANDLE_MCARD_OBSERVABILITY_TRACE}{}", trace_id);
335
336    let record = crate::layer2::record_store::read_handle_record(&conn, &handle)
337        .map_err(|error| error.to_string())?.ok_or("content handle is missing")?;
338    let content_hash = record.hash;
339    let content = String::from_utf8(record.content).map_err(|error| error.to_string())?;
340
341    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
342    Ok(TraceSpanRecord {
343        trace_id: v.get("trace_id").and_then(|x| x.as_str()).unwrap_or(trace_id).to_string(),
344        span_id: v.get("span_id").and_then(|x| x.as_str()).unwrap_or("").to_string(),
345        parent_span_id: v.get("parent_span_id").and_then(|x| x.as_str()).map(|x| x.to_string()),
346        pcard_handle: v.get("pcard_handle").and_then(|x| x.as_str()).unwrap_or("").to_string(),
347        vcard_hash: v.get("vcard_hash").and_then(|x| x.as_str()).unwrap_or("").to_string(),
348        duration_ms: v.get("duration_ms").and_then(|x| x.as_u64()).unwrap_or(0),
349        timestamp: v.get("timestamp").and_then(|x| x.as_str()).unwrap_or("").to_string(),
350        handle,
351        content_hash,
352    })
353}
354
355/// Retrieves metric MCard content by `metric_name`.
356pub fn get_metric(
357    db_name_or_path: &str,
358    clm_root: Option<&str>,
359    metric_name: &str,
360) -> Result<MetricRecord, String> {
361    let db_path = resolve_db_path(db_name_or_path, clm_root);
362    if !db_path.exists() {
363        return Err(format!("Database not found for metric {}", metric_name));
364    }
365    let conn = Connection::open(&db_path).map_err(|e| e.to_string())?;
366    let handle = format!("{HANDLE_MCARD_OBSERVABILITY_METRIC}{}", metric_name);
367
368    let record = crate::layer2::record_store::read_handle_record(&conn, &handle)
369        .map_err(|error| error.to_string())?.ok_or("content handle is missing")?;
370    let content_hash = record.hash;
371    let content = String::from_utf8(record.content).map_err(|error| error.to_string())?;
372
373    let v: serde_json::Value = serde_json::from_str(&content).map_err(|e| e.to_string())?;
374    Ok(MetricRecord {
375        metric_name: v.get("metric_name").and_then(|x| x.as_str()).unwrap_or(metric_name).to_string(),
376        value: v.get("value").and_then(|x| x.as_f64()).unwrap_or(0.0),
377        labels: v.get("labels").cloned().unwrap_or_else(|| serde_json::json!({})),
378        timestamp: v.get("timestamp").and_then(|x| x.as_str()).unwrap_or("").to_string(),
379        handle,
380        content_hash,
381    })
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387
388    #[test]
389    fn test_observability_pipeline() {
390        let db_path = "/tmp/test_observability.db";
391        let _ = std::fs::remove_file(db_path);
392
393        // 1. Configure observability
394        let cfg = configure_observability(db_path, None, "http://localhost:4317", "http://localhost:3100", "http://localhost:9009", Some(1.0)).unwrap();
395        assert_eq!(cfg.tempo_endpoint, "http://localhost:4317");
396
397        // 2. Emit trace span
398        let trace = emit_trace_span(db_path, None, "tr_001", "sp_001", None, "pcard:auth/verify", "0xhash123", 42).unwrap();
399        assert_eq!(trace.trace_id, "tr_001");
400
401        // 3. Query trace span
402        let fetched_trace = get_trace(db_path, None, "tr_001").unwrap();
403        assert_eq!(fetched_trace.duration_ms, 42);
404        assert_eq!(fetched_trace.vcard_hash, "0xhash123");
405
406        // 4. Record metric
407        let metric = record_metric(db_path, None, "pkc_auth_success_total", 1.0, Some(r#"{"provider":"zitadel"}"#)).unwrap();
408        assert_eq!(metric.metric_name, "pkc_auth_success_total");
409
410        // 5. Query metric
411        let fetched_metric = get_metric(db_path, None, "pkc_auth_success_total").unwrap();
412        assert_eq!(fetched_metric.value, 1.0);
413
414        // 6. Emit structured log
415        let log_rec = emit_structured_log(db_path, None, "tr_001", "INFO", "0xhash123", "did:key:z6MkAgent", "Auth challenge verified").unwrap();
416        assert_eq!(log_rec.level, "INFO");
417
418        let _ = std::fs::remove_file(db_path);
419    }
420}