Struct SessionTracer 

pub struct SessionTracer { /* private fields */ }

Session tracer for recording traces.

Provides a high-level API for recording session traces with timesteps, events, and messages. Supports real-time persistence and hook callbacks.

Example

use synth_ai_core::tracing::{SessionTracer, LibsqlTraceStorage, TracingEvent, LMCAISEvent};
use std::sync::Arc;

let storage = Arc::new(LibsqlTraceStorage::new_memory().await?);
let tracer = SessionTracer::new(storage);

let session_id = tracer.start_session(None, Default::default()).await?;
tracer.start_timestep("step-1", Some(1), Default::default()).await?;
tracer.record_event(TracingEvent::Cais(LMCAISEvent { ... })).await?;
tracer.end_timestep().await?;
let trace = tracer.end_session(true).await?;

Implementations

impl SessionTracer

pub fn new(storage: Arc<dyn TraceStorage>) -> SessionTracer

Create a new session tracer with a storage backend.

pub fn with_hooks( storage: Arc<dyn TraceStorage>, hooks: HookManager, ) -> SessionTracer

Create a new session tracer with custom hooks.

pub fn set_auto_save(&mut self, auto_save: bool)

Set whether to auto-save events to storage.

pub async fn register_hook( &self, event: HookEvent, callback: Arc<dyn Fn(&HookContext) + Send + Sync>, priority: i32, )

Register a hook callback.

pub async fn start_session( &self, session_id: Option<&str>, metadata: HashMap<String, Value>, ) -> Result<String, TracingError>

Start a new session.

Arguments

• session_id - Optional session ID. If None, a UUID will be generated.
• metadata - Session-level metadata.

Returns

The session ID.

pub async fn end_session( &self, save: bool, ) -> Result<SessionTrace, TracingError>

End the current session.

Arguments

• save - Whether to save the session to storage (ignored if auto_save is true).

Returns

The completed session trace.

pub async fn current_session_id(&self) -> Option<String>

Get the current session ID (if any).

pub async fn query( &self, sql: &str, params: QueryParams, ) -> Result<Vec<Value>, TracingError>

Execute a raw SQL query against the underlying storage.

pub async fn start_timestep( &self, step_id: &str, turn_number: Option<i32>, metadata: HashMap<String, Value>, ) -> Result<(), TracingError>

Start a new timestep.

Arguments

• step_id - Unique step identifier.
• turn_number - Optional conversation turn number.
• metadata - Step-level metadata.

pub async fn end_timestep(&self) -> Result<(), TracingError>

End the current timestep.

pub async fn current_step_id(&self) -> Option<String>

Get the current step ID (if any).

pub async fn record_event( &self, event: TracingEvent, ) -> Result<Option<i64>, TracingError>

Record an event.

Arguments

• event - The event to record.

Returns

The database ID of the event (if auto_save is enabled).

pub async fn record_message( &self, content: MessageContent, message_type: &str, metadata: HashMap<String, Value>, ) -> Result<Option<i64>, TracingError>

Record a message.

Arguments

• content - Message content.
• message_type - Type of message (user, assistant, system, tool_use, tool_result).
• metadata - Message metadata.

Returns

The database ID of the message (if auto_save is enabled).

pub async fn record_outcome_reward( &self, reward: OutcomeReward, ) -> Result<Option<i64>, TracingError>

Record an outcome (session-level) reward.

pub async fn record_event_reward( &self, event_id: i64, reward: EventReward, ) -> Result<Option<i64>, TracingError>

Record an event-level reward.

pub async fn get_session( &self, session_id: &str, ) -> Result<Option<SessionTrace>, TracingError>

Get a session trace by ID from storage.

pub async fn delete_session( &self, session_id: &str, ) -> Result<bool, TracingError>

Delete a session from storage.