Skip to main content

mojentic/tracer/
tracer_events.rs

1//! Tracer event types for tracking system interactions
2//!
3//! This module defines the core event types used by the tracer system to record
4//! LLM calls, tool executions, and agent interactions. All events implement the
5//! `TracerEvent` trait which provides timestamps, correlation IDs, and printable summaries.
6
7use crate::llm::models::ResponseEvidence;
8use chrono::{DateTime, Local};
9use serde::{Deserialize, Serialize};
10use std::any::Any;
11use std::collections::HashMap;
12
13/// Trait for filtering tracer events
14///
15/// Implement this trait to create custom event filters. This trait is used
16/// instead of raw closure types to avoid type complexity warnings.
17pub trait EventFilterFn: Send + Sync {
18    /// Test whether an event passes the filter
19    fn matches(&self, event: &dyn TracerEvent) -> bool;
20}
21
22/// Implement EventFilterFn for any function that matches the signature
23impl<F> EventFilterFn for F
24where
25    F: Fn(&dyn TracerEvent) -> bool + Send + Sync,
26{
27    fn matches(&self, event: &dyn TracerEvent) -> bool {
28        self(event)
29    }
30}
31
32/// Base trait for all tracer events
33///
34/// Tracer events are used to track system interactions for observability purposes.
35/// They are distinct from regular events which are used for agent communication.
36pub trait TracerEvent: Send + Sync {
37    /// Get the timestamp when the event occurred
38    fn timestamp(&self) -> f64;
39
40    /// Get the correlation ID for tracing related events
41    fn correlation_id(&self) -> &str;
42
43    /// Get the source of the event
44    fn source(&self) -> &str;
45
46    /// Get a formatted string summary of the event
47    fn printable_summary(&self) -> String;
48
49    /// Expose the concrete event for downcasting, when the event type allows it.
50    ///
51    /// The built-in events return `Some(self)`, so an [`crate::tracer::EventCallback`]
52    /// can read typed fields, for example the evidence on an
53    /// [`LlmResponseTracerEvent`]:
54    ///
55    /// ```
56    /// use mojentic::tracer::{LlmResponseTracerEvent, TracerEvent};
57    ///
58    /// fn finish_reason(event: &dyn TracerEvent) -> Option<String> {
59    ///     event
60    ///         .as_any()?
61    ///         .downcast_ref::<LlmResponseTracerEvent>()?
62    ///         .evidence
63    ///         .finish_reason
64    ///         .clone()
65    /// }
66    /// ```
67    fn as_any(&self) -> Option<&dyn Any> {
68        None
69    }
70}
71
72/// Records when an LLM is called with specific messages
73#[derive(Debug, Clone, Serialize, Deserialize)]
74pub struct LlmCallTracerEvent {
75    /// Timestamp when the event occurred (Unix timestamp)
76    pub timestamp: f64,
77    /// UUID string that is copied from cause-to-affect for tracing events
78    pub correlation_id: String,
79    /// Source of the event
80    pub source: String,
81    /// The LLM model that was used
82    pub model: String,
83    /// The messages sent to the LLM (simplified representation)
84    pub messages: Vec<HashMap<String, serde_json::Value>>,
85    /// Caller-selected temperature; absent when delegated to provider settings.
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub temperature: Option<f64>,
88    /// The tools available to the LLM, if any
89    pub tools: Option<Vec<HashMap<String, serde_json::Value>>>,
90}
91
92impl TracerEvent for LlmCallTracerEvent {
93    fn timestamp(&self) -> f64 {
94        self.timestamp
95    }
96
97    fn correlation_id(&self) -> &str {
98        &self.correlation_id
99    }
100
101    fn source(&self) -> &str {
102        &self.source
103    }
104
105    fn printable_summary(&self) -> String {
106        let dt = DateTime::from_timestamp(self.timestamp as i64, 0)
107            .unwrap_or_else(|| DateTime::from_timestamp(0, 0).unwrap())
108            .with_timezone(&Local);
109        let time_str = dt.format("%H:%M:%S%.3f").to_string();
110
111        let mut summary = format!(
112            "[{}] LlmCallTracerEvent (correlation_id: {})\n   Model: {}",
113            time_str, self.correlation_id, self.model
114        );
115
116        if !self.messages.is_empty() {
117            let msg_count = self.messages.len();
118            let plural = if msg_count != 1 { "s" } else { "" };
119            summary.push_str(&format!("\n   Messages: {} message{}", msg_count, plural));
120        }
121
122        if let Some(temperature) = self.temperature {
123            summary.push_str(&format!("\n   Temperature: {}", temperature));
124        }
125
126        if let Some(tools) = &self.tools {
127            let tool_names: Vec<String> = tools
128                .iter()
129                .filter_map(|t| t.get("name").and_then(|n| n.as_str()).map(|s| s.to_string()))
130                .collect();
131            if !tool_names.is_empty() {
132                summary.push_str(&format!("\n   Available Tools: {}", tool_names.join(", ")));
133            }
134        }
135
136        summary
137    }
138
139    fn as_any(&self) -> Option<&dyn Any> {
140        Some(self)
141    }
142}
143
144/// Records when an LLM responds to a call
145#[derive(Debug, Clone, Serialize, Deserialize)]
146pub struct LlmResponseTracerEvent {
147    /// Timestamp when the event occurred (Unix timestamp)
148    pub timestamp: f64,
149    /// UUID string that is copied from cause-to-affect for tracing events
150    pub correlation_id: String,
151    /// Source of the event
152    pub source: String,
153    /// The LLM model that was used
154    pub model: String,
155    /// The content of the LLM response
156    pub content: String,
157    /// Any tool calls made by the LLM
158    pub tool_calls: Option<Vec<HashMap<String, serde_json::Value>>>,
159    /// Duration of the LLM call in milliseconds
160    pub call_duration_ms: Option<f64>,
161    /// Provider-reported usage, provider model, finish reason and metadata.
162    ///
163    /// Serialized as the flat fields `usage`, `provider_model`,
164    /// `finish_reason` and `metadata`. Unknown values stay null.
165    #[serde(flatten)]
166    pub evidence: ResponseEvidence,
167}
168
169impl TracerEvent for LlmResponseTracerEvent {
170    fn timestamp(&self) -> f64 {
171        self.timestamp
172    }
173
174    fn correlation_id(&self) -> &str {
175        &self.correlation_id
176    }
177
178    fn source(&self) -> &str {
179        &self.source
180    }
181
182    fn printable_summary(&self) -> String {
183        let dt = DateTime::from_timestamp(self.timestamp as i64, 0)
184            .unwrap_or_else(|| DateTime::from_timestamp(0, 0).unwrap())
185            .with_timezone(&Local);
186        let time_str = dt.format("%H:%M:%S%.3f").to_string();
187
188        let mut summary = format!(
189            "[{}] LlmResponseTracerEvent (correlation_id: {})\n   Model: {}",
190            time_str, self.correlation_id, self.model
191        );
192
193        if !self.content.is_empty() {
194            let content_preview = if self.content.len() > 100 {
195                format!("{}...", &self.content[..100])
196            } else {
197                self.content.clone()
198            };
199            summary.push_str(&format!("\n   Content: {}", content_preview));
200        }
201
202        if let Some(tool_calls) = &self.tool_calls {
203            let tool_count = tool_calls.len();
204            let plural = if tool_count != 1 { "s" } else { "" };
205            summary.push_str(&format!("\n   Tool Calls: {} call{}", tool_count, plural));
206        }
207
208        if let Some(duration) = self.call_duration_ms {
209            summary.push_str(&format!("\n   Duration: {:.2}ms", duration));
210        }
211
212        if let Some(provider_model) = &self.evidence.provider_model {
213            summary.push_str(&format!("\n   Provider Model: {}", provider_model));
214        }
215
216        if let Some(finish_reason) = &self.evidence.finish_reason {
217            summary.push_str(&format!("\n   Finish Reason: {}", finish_reason));
218        }
219
220        if let Some(usage) = &self.evidence.usage {
221            summary.push_str(&format!("\n   Usage: {}", usage));
222        }
223
224        summary
225    }
226
227    fn as_any(&self) -> Option<&dyn Any> {
228        Some(self)
229    }
230}
231
232/// Records when a tool is called during agent execution
233#[derive(Debug, Clone, Serialize, Deserialize)]
234pub struct ToolCallTracerEvent {
235    /// Timestamp when the event occurred (Unix timestamp)
236    pub timestamp: f64,
237    /// UUID string that is copied from cause-to-affect for tracing events
238    pub correlation_id: String,
239    /// Source of the event
240    pub source: String,
241    /// Name of the tool that was called
242    pub tool_name: String,
243    /// Arguments provided to the tool
244    pub arguments: HashMap<String, serde_json::Value>,
245    /// Result returned by the tool (as JSON value)
246    pub result: serde_json::Value,
247    /// Name of the agent or component that called the tool
248    pub caller: Option<String>,
249    /// Duration of the tool call in milliseconds
250    pub call_duration_ms: Option<f64>,
251}
252
253impl TracerEvent for ToolCallTracerEvent {
254    fn timestamp(&self) -> f64 {
255        self.timestamp
256    }
257
258    fn correlation_id(&self) -> &str {
259        &self.correlation_id
260    }
261
262    fn source(&self) -> &str {
263        &self.source
264    }
265
266    fn printable_summary(&self) -> String {
267        let dt = DateTime::from_timestamp(self.timestamp as i64, 0)
268            .unwrap_or_else(|| DateTime::from_timestamp(0, 0).unwrap())
269            .with_timezone(&Local);
270        let time_str = dt.format("%H:%M:%S%.3f").to_string();
271
272        let mut summary = format!(
273            "[{}] ToolCallTracerEvent (correlation_id: {})\n   Tool: {}",
274            time_str, self.correlation_id, self.tool_name
275        );
276
277        if !self.arguments.is_empty() {
278            summary.push_str(&format!("\n   Arguments: {:?}", self.arguments));
279        }
280
281        let result_str = self.result.to_string();
282        let result_preview = if result_str.len() > 100 {
283            format!("{}...", &result_str[..100])
284        } else {
285            result_str
286        };
287        summary.push_str(&format!("\n   Result: {}", result_preview));
288
289        if let Some(caller) = &self.caller {
290            summary.push_str(&format!("\n   Caller: {}", caller));
291        }
292
293        if let Some(duration) = self.call_duration_ms {
294            summary.push_str(&format!("\n   Duration: {:.2}ms", duration));
295        }
296
297        summary
298    }
299
300    fn as_any(&self) -> Option<&dyn Any> {
301        Some(self)
302    }
303}
304
305/// Records the end-to-end execution of a parallel tool batch.
306///
307/// Per-call detail still lands as `ToolCallTracerEvent` events; the
308/// batch event lets observers measure parallelism gains and correlate
309/// calls dispatched together.
310#[derive(Debug, Clone, Serialize, Deserialize)]
311pub struct ToolBatchTracerEvent {
312    pub timestamp: f64,
313    pub correlation_id: String,
314    pub source: String,
315    pub batch_id: String,
316    pub tool_names: Vec<String>,
317    pub success_count: usize,
318    pub failure_count: usize,
319    pub call_duration_ms: f64,
320    pub caller: Option<String>,
321}
322
323impl TracerEvent for ToolBatchTracerEvent {
324    fn timestamp(&self) -> f64 {
325        self.timestamp
326    }
327
328    fn correlation_id(&self) -> &str {
329        &self.correlation_id
330    }
331
332    fn source(&self) -> &str {
333        &self.source
334    }
335
336    fn printable_summary(&self) -> String {
337        let dt = DateTime::from_timestamp(self.timestamp as i64, 0)
338            .unwrap_or_else(|| DateTime::from_timestamp(0, 0).unwrap())
339            .with_timezone(&Local);
340        let time_str = dt.format("%H:%M:%S%.3f").to_string();
341        format!(
342            "[{}] ToolBatchTracerEvent (correlation_id: {})\n   Batch: {}\n   Tools: {}\n   Outcome: {} ok / {} failed\n   Duration: {:.2}ms",
343            time_str,
344            self.correlation_id,
345            self.batch_id,
346            self.tool_names.join(", "),
347            self.success_count,
348            self.failure_count,
349            self.call_duration_ms
350        )
351    }
352
353    fn as_any(&self) -> Option<&dyn Any> {
354        Some(self)
355    }
356}
357
358/// Records interactions between agents
359#[derive(Debug, Clone, Serialize, Deserialize)]
360pub struct AgentInteractionTracerEvent {
361    /// Timestamp when the event occurred (Unix timestamp)
362    pub timestamp: f64,
363    /// UUID string that is copied from cause-to-affect for tracing events
364    pub correlation_id: String,
365    /// Source of the event
366    pub source: String,
367    /// Name of the agent sending the event
368    pub from_agent: String,
369    /// Name of the agent receiving the event
370    pub to_agent: String,
371    /// Type of event being processed
372    pub event_type: String,
373    /// Unique identifier for the event
374    pub event_id: Option<String>,
375}
376
377impl TracerEvent for AgentInteractionTracerEvent {
378    fn timestamp(&self) -> f64 {
379        self.timestamp
380    }
381
382    fn correlation_id(&self) -> &str {
383        &self.correlation_id
384    }
385
386    fn source(&self) -> &str {
387        &self.source
388    }
389
390    fn printable_summary(&self) -> String {
391        let dt = DateTime::from_timestamp(self.timestamp as i64, 0)
392            .unwrap_or_else(|| DateTime::from_timestamp(0, 0).unwrap())
393            .with_timezone(&Local);
394        let time_str = dt.format("%H:%M:%S%.3f").to_string();
395
396        let mut summary = format!(
397            "[{}] AgentInteractionTracerEvent (correlation_id: {})\n   From: {} → To: {}\n   Event Type: {}",
398            time_str, self.correlation_id, self.from_agent, self.to_agent, self.event_type
399        );
400
401        if let Some(event_id) = &self.event_id {
402            summary.push_str(&format!("\n   Event ID: {}", event_id));
403        }
404
405        summary
406    }
407
408    fn as_any(&self) -> Option<&dyn Any> {
409        Some(self)
410    }
411}
412
413#[cfg(test)]
414mod tests {
415    use super::*;
416    use std::time::{SystemTime, UNIX_EPOCH};
417
418    fn current_timestamp() -> f64 {
419        SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_secs_f64()
420    }
421
422    #[test]
423    fn test_llm_call_event() {
424        let event = LlmCallTracerEvent {
425            timestamp: current_timestamp(),
426            correlation_id: "test-123".to_string(),
427            source: "test".to_string(),
428            model: "llama3.2".to_string(),
429            messages: vec![],
430            temperature: Some(0.7),
431            tools: None,
432        };
433
434        assert_eq!(event.correlation_id(), "test-123");
435        assert_eq!(event.model, "llama3.2");
436        assert!((event.temperature.expect("explicit temperature") - 0.7).abs() < f64::EPSILON);
437
438        let summary = event.printable_summary();
439        assert!(summary.contains("LlmCallTracerEvent"));
440        assert!(summary.contains("test-123"));
441        assert!(summary.contains("llama3.2"));
442    }
443
444    #[test]
445    fn test_llm_response_event() {
446        let event = LlmResponseTracerEvent {
447            timestamp: current_timestamp(),
448            correlation_id: "test-456".to_string(),
449            source: "test".to_string(),
450            model: "llama3.2".to_string(),
451            content: "Hello, world!".to_string(),
452            tool_calls: None,
453            call_duration_ms: Some(150.5),
454            evidence: ResponseEvidence::default(),
455        };
456
457        assert_eq!(event.content, "Hello, world!");
458        assert_eq!(event.call_duration_ms, Some(150.5));
459
460        let summary = event.printable_summary();
461        assert!(summary.contains("LlmResponseTracerEvent"));
462        assert!(summary.contains("Hello, world!"));
463        assert!(summary.contains("150.5"));
464    }
465
466    fn evidence() -> ResponseEvidence {
467        ResponseEvidence {
468            usage: Some(serde_json::json!({"prompt_tokens": 3, "completion_tokens": 5})),
469            provider_model: Some("gpt-4o-2024-08-06".to_string()),
470            finish_reason: Some("stop".to_string()),
471            metadata: HashMap::from([("id".to_string(), serde_json::json!("chatcmpl-1"))]),
472        }
473    }
474
475    fn response_event(evidence: ResponseEvidence) -> LlmResponseTracerEvent {
476        LlmResponseTracerEvent {
477            timestamp: current_timestamp(),
478            correlation_id: "corr".to_string(),
479            source: "test".to_string(),
480            model: "gpt-4o".to_string(),
481            content: "Hi".to_string(),
482            tool_calls: None,
483            call_duration_ms: None,
484            evidence,
485        }
486    }
487
488    #[test]
489    fn llm_response_event_serializes_evidence_as_flat_fields() {
490        let json = serde_json::to_value(response_event(evidence())).unwrap();
491
492        assert_eq!(json["model"], "gpt-4o");
493        assert_eq!(json["provider_model"], "gpt-4o-2024-08-06");
494        assert_eq!(json["finish_reason"], "stop");
495        assert_eq!(json["usage"], serde_json::json!({"prompt_tokens": 3, "completion_tokens": 5}));
496        assert_eq!(json["metadata"], serde_json::json!({"id": "chatcmpl-1"}));
497    }
498
499    #[test]
500    fn llm_response_event_serializes_unknown_evidence_as_null() {
501        let json = serde_json::to_value(response_event(ResponseEvidence::default())).unwrap();
502
503        assert!(json["usage"].is_null());
504        assert!(json["provider_model"].is_null());
505        assert!(json["finish_reason"].is_null());
506    }
507
508    #[test]
509    fn llm_response_event_deserializes_records_without_evidence() {
510        let json = serde_json::json!({
511            "timestamp": 1.0,
512            "correlation_id": "corr",
513            "source": "test",
514            "model": "gpt-4o",
515            "content": "Hi",
516            "tool_calls": null,
517            "call_duration_ms": null
518        });
519
520        let event: LlmResponseTracerEvent = serde_json::from_value(json).unwrap();
521
522        assert_eq!(event.evidence, ResponseEvidence::default());
523    }
524
525    #[test]
526    fn llm_response_summary_shows_reported_evidence() {
527        let summary = response_event(evidence()).printable_summary();
528
529        assert!(summary.contains("Provider Model: gpt-4o-2024-08-06"));
530        assert!(summary.contains("Finish Reason: stop"));
531        assert!(summary.contains("\"prompt_tokens\":3"));
532    }
533
534    #[test]
535    fn built_in_events_downcast_through_as_any() {
536        let event: Box<dyn TracerEvent> = Box::new(response_event(evidence()));
537
538        let typed = event
539            .as_any()
540            .and_then(|any| any.downcast_ref::<LlmResponseTracerEvent>())
541            .expect("response event downcasts");
542
543        assert_eq!(typed.evidence, evidence());
544    }
545
546    #[test]
547    fn test_tool_call_event() {
548        let mut args = HashMap::new();
549        args.insert("input".to_string(), serde_json::json!("test"));
550
551        let event = ToolCallTracerEvent {
552            timestamp: current_timestamp(),
553            correlation_id: "test-789".to_string(),
554            source: "test".to_string(),
555            tool_name: "example_tool".to_string(),
556            arguments: args,
557            result: serde_json::json!({"output": "result"}),
558            caller: Some("agent1".to_string()),
559            call_duration_ms: Some(25.0),
560        };
561
562        assert_eq!(event.tool_name, "example_tool");
563        assert_eq!(event.caller, Some("agent1".to_string()));
564
565        let summary = event.printable_summary();
566        assert!(summary.contains("ToolCallTracerEvent"));
567        assert!(summary.contains("example_tool"));
568    }
569
570    #[test]
571    fn test_agent_interaction_event() {
572        let event = AgentInteractionTracerEvent {
573            timestamp: current_timestamp(),
574            correlation_id: "test-abc".to_string(),
575            source: "test".to_string(),
576            from_agent: "agent1".to_string(),
577            to_agent: "agent2".to_string(),
578            event_type: "message".to_string(),
579            event_id: Some("evt-123".to_string()),
580        };
581
582        assert_eq!(event.from_agent, "agent1");
583        assert_eq!(event.to_agent, "agent2");
584
585        let summary = event.printable_summary();
586        assert!(summary.contains("AgentInteractionTracerEvent"));
587        assert!(summary.contains("agent1"));
588        assert!(summary.contains("agent2"));
589    }
590}