Tracing

Observability and distributed tracing in PraisonAI Rust SDK

Tracing provides observability for agent execution, tracking spans across LLM calls, tool executions, and workflows.

Quick Start

1. Create a Trace

   use praisonai::trace::{TraceContext, SpanKind};
   
   let mut ctx = TraceContext::new("agent-execution");
   
   // Start a span
   let span_id = ctx.start_span("process-request", SpanKind::Agent);
   
   // Do work...
   ctx.add_event("received_input");
   ctx.set_attribute("input_length", 42);
   
   // End span
   ctx.end_span(&span_id);
   
   println!("Trace completed with {} spans", ctx.span_count());

2. Nested Spans

   use praisonai::trace::{TraceContext, SpanKind};
   
   let mut ctx = TraceContext::new("workflow");
   
   let workflow_span = ctx.start_span("workflow", SpanKind::Workflow);
   
       let agent_span = ctx.start_span("agent-task", SpanKind::Agent);
   
           let llm_span = ctx.start_span("llm-call", SpanKind::Llm);
           // LLM call happens here
           ctx.end_span(&llm_span);
   
       ctx.end_span(&agent_span);
   
   ctx.end_span(&workflow_span);
   
   // Export trace
   let json = ctx.to_json();

User Interaction Flow

TraceContext

Main tracing context that manages spans.

pub struct TraceContext {
    pub id: String,
    pub name: String,
    pub attributes: HashMap<String, Value>,
}

Methods

) -> Self | Create trace context | | elapsed() | fn elapsed(&self) -> Duration | Time since trace start | | start_span(name, kind) | fn start_span(&mut self, impl Into

, SpanKind) -> String | Start span, returns ID | | end_span(id) | fn end_span(&mut self, &str) | End span by ID | | current_span_id() | fn current_span_id(&self) -> Option<&str> | Get current span ID | | get_span(id) | fn get_span(&self, &str) -> Option<&Span> | Get span by ID | | add_event(name) | fn add_event(&mut self, impl Into

) | Add event to current span | | set_attribute(key, value) | fn set_attribute(&mut self, impl Into

, impl Serialize) | Set attribute on current | | spans() | fn spans(&self) -> &[Span] | Get all spans | | span_count() | fn span_count(&self) -> usize | Number of spans | | to_json() | fn to_json(&self) -> Value` | Export as JSON |

SpanKind

Type of operation being traced.

pub enum SpanKind {
    Internal,   // default - Internal operation
    Llm,        // LLM call
    Tool,       // Tool execution
    Agent,      // Agent processing
    Workflow,   // Workflow execution
    Memory,     // Memory operation
    Network,    // Network/API call
    Custom,     // Custom operation
}

SpanStatus

Status of a span.

pub enum SpanStatus {
    Unset,  // default - Not set
    Ok,     // Success
    Error,  // Error occurred
}

Span

Represents a unit of work.

pub struct Span {
    pub id: String,
    pub parent_id: Option<String>,
    pub trace_id: String,
    pub name: String,
    pub kind: SpanKind,
    pub status: SpanStatus,
    pub start_offset: Duration,
    pub end_offset: Option<Duration>,
    pub duration: Option<Duration>,
    pub attributes: HashMap<String, Value>,
    pub events: Vec<SpanEvent>,
    pub error_message: Option<String>,
}

Methods

) -> Self | Set parent | | set_attribute(key, value) | fn set_attribute(&mut self, impl Into

, impl Serialize) | Add attribute | | add_event(event) | fn add_event(&mut self, SpanEvent) | Add event | | end(offset) | fn end(&mut self, Duration) | End span | | set_error(message) | fn set_error(&mut self, impl Into

) | Mark as error | | is_ended() | fn is_ended(&self) -> bool` | Check if ended |

SpanEvent

Events within a span.

pub struct SpanEvent {
    pub name: String,
    pub timestamp: Duration,
    pub attributes: HashMap<String, Value>,
}

Methods

, Duration) -> Self | Create event | | with_attribute(key, value) | fn with_attribute(self, impl Into

, impl Serialize) -> Self` | Add attribute |

TraceExporter Trait

Export traces to various backends.

pub trait TraceExporter: Send + Sync {
    fn export(&self, trace: &TraceContext) -> Result<(), Box<dyn Error>>;
}

Built-in Exporters

Example: Full Tracing

use praisonai::trace::{TraceContext, SpanKind, ConsoleExporter, TraceExporter};

let mut ctx = TraceContext::new("agent-request");

// Agent span
let agent_span = ctx.start_span("handle-request", SpanKind::Agent);
ctx.set_attribute("user_id", "user-123");

    // LLM span
    let llm_span = ctx.start_span("gpt-4-call", SpanKind::Llm);
    ctx.set_attribute("model", "gpt-4o");
    ctx.set_attribute("tokens", 150);
    ctx.add_event("response_received");
    ctx.end_span(&llm_span);

    // Tool span
    let tool_span = ctx.start_span("search-tool", SpanKind::Tool);
    ctx.set_attribute("query", "rust programming");
    ctx.end_span(&tool_span);

ctx.end_span(&agent_span);

// Export
let exporter = ConsoleExporter;
exporter.export(&ctx).unwrap();

Best Practices

Related