> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Trace Module > Track agent execution with context events and trace sinks Track and monitor agent execution with detailed context events and customizable trace sinks. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR subgraph "Trace System" A[🤖 Agent] --> B[📊 Events] B --> C{🔄 Emitter} C --> D[📝 List Sink] C --> E[☁️ Cloud Sink] C --> F[📁 File Sink] end classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff classDef events fill:#F59E0B,stroke:#7C90A0,color:#fff classDef emitter fill:#189AB4,stroke:#7C90A0,color:#fff classDef sink fill:#10B981,stroke:#7C90A0,color:#fff class A agent class B events class C emitter class D,E,F sink classDef agent fill:#8B0000,color:#fff classDef tool fill:#189AB4,color:#fff ``` ## Quick Start **1. Create a Trace Sink** ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { TraceSink, ContextEventType } from 'praisonai'; const sink = new TraceSink(); // Emit events sink.emit({ type: ContextEventType.AGENT_START, timestamp: new Date(), agentName: "Assistant", data: { input: "Hello!" } }); ``` **2. Use Context Trace Emitter** ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { ContextTraceEmitter, ContextListSink } from 'praisonai'; const sink = new ContextListSink(); const emitter = new ContextTraceEmitter(sink); emitter.agentStart("Assistant", "Hello!"); emitter.agentEnd("Assistant", "Hi there!"); console.log(sink.getEvents()); ``` *** ## Event Types ### Context Event Types ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { ContextEventType } from 'praisonai'; ContextEventType.AGENT_START // Agent begins processing ContextEventType.AGENT_END // Agent finishes processing ContextEventType.TOOL_START // Tool execution begins ContextEventType.TOOL_END // Tool execution ends ContextEventType.LLM_START // LLM call begins ContextEventType.LLM_END // LLM call ends ContextEventType.ERROR // Error occurred ContextEventType.MESSAGE // Message event ContextEventType.HANDOFF // Agent handoff ContextEventType.MEMORY_READ // Memory read operation ContextEventType.MEMORY_WRITE // Memory write operation ``` ### General Event Types ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { EventType } from 'praisonai'; EventType.START // Start event EventType.END // End event EventType.ERROR // Error event EventType.INFO // Info event EventType.DEBUG // Debug event EventType.TRACE // Trace event ``` ### Message Types ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { MessageType } from 'praisonai'; MessageType.USER // User message MessageType.ASSISTANT // Assistant message MessageType.SYSTEM // System message MessageType.TOOL // Tool message MessageType.FUNCTION // Function message ``` *** ## Context Event ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} interface ContextEvent { type: ContextEventType; // Event type timestamp: Date; // When it occurred agentName?: string; // Agent name toolName?: string; // Tool name (if tool event) data?: Record; // Event data metadata?: Record; // Additional metadata traceId?: string; // Trace identifier spanId?: string; // Span identifier parentSpanId?: string; // Parent span ID } ``` ### Create Events ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { createContextEvent, ContextEventType } from 'praisonai'; const event = createContextEvent(ContextEventType.AGENT_START, { input: "User query", agentName: "Assistant" }); ``` *** ## Trace Sinks ### Base TraceSink ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { TraceSink } from 'praisonai'; const sink = new TraceSink(); // Emit event sink.emit({ type: ContextEventType.AGENT_START, timestamp: new Date() }); // Get all events const events = sink.getEvents(); // Clear events sink.clear(); // Flush and close sink.close(); ``` ### ContextListSink Stores events in memory for later retrieval: ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { ContextListSink } from 'praisonai'; const sink = new ContextListSink(); sink.emit({ type: ContextEventType.AGENT_START, timestamp: new Date() }); sink.emit({ type: ContextEventType.AGENT_END, timestamp: new Date() }); // Get all events const events = sink.getEvents(); console.log(`Captured ${events.length} events`); ``` ### ContextNoOpSink Does nothing - useful for disabling tracing: ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { ContextNoOpSink } from 'praisonai'; const sink = new ContextNoOpSink(); sink.emit({ type: ContextEventType.AGENT_START, timestamp: new Date() }); // Event is discarded ``` *** ## Context Trace Emitter High-level API for emitting trace events: ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { ContextTraceEmitter, ContextListSink } from 'praisonai'; const sink = new ContextListSink(); const emitter = new ContextTraceEmitter(sink); // Agent events emitter.agentStart("Assistant", "Hello!"); emitter.agentEnd("Assistant", "Response here"); // Tool events emitter.toolStart("search", { query: "AI news" }); emitter.toolEnd("search", { results: [...] }); // LLM events emitter.llmStart("gpt-4o", messages); emitter.llmEnd("gpt-4o", response); // Error events emitter.error(new Error("Something failed"), { context: "tool_call" }); // Custom events emitter.emit(ContextEventType.MESSAGE, { content: "Custom message" }); ``` *** ## Trace Context Global trace context management: ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { traceContext, trackWorkflow } from 'praisonai'; // Get current trace context const ctx = traceContext(); console.log(ctx.traceId, ctx.spanId); // Track a workflow const result = await trackWorkflow("my-workflow", async () => { // Your workflow code here return "result"; }); ``` *** ## Custom Trace Sink Create custom sinks for external integrations: ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { TraceSinkProtocol, ContextEvent } from 'praisonai'; class CloudTraceSink implements TraceSinkProtocol { private buffer: ContextEvent[] = []; async emit(event: ContextEvent): Promise { this.buffer.push(event); if (this.buffer.length >= 10) { await this.flush(); } } async flush(): Promise { if (this.buffer.length === 0) return; await fetch('https://traces.example.com/api', { method: 'POST', body: JSON.stringify(this.buffer) }); this.buffer = []; } async close(): Promise { await this.flush(); } } ``` *** ## Common Patterns > [tab] Debug Tracing > > ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} > import { ContextTraceEmitter, ContextListSink } from 'praisonai'; > > const sink = new ContextListSink(); > const emitter = new ContextTraceEmitter(sink); > > // Run agent with tracing > emitter.agentStart("Assistant", query); > const result = await agent.start(query); > emitter.agentEnd("Assistant", result); > > // Analyze trace > const events = sink.getEvents(); > const duration = events[1].timestamp - events[0].timestamp; > console.log(`Agent took ${duration}ms`); > ``` > [tab] Error Tracking > > ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} > import { ContextTraceEmitter, TraceSink } from 'praisonai'; > > const emitter = new ContextTraceEmitter(new TraceSink()); > > try { > emitter.toolStart("api_call", { url: "..." }); > const result = await apiCall(); > emitter.toolEnd("api_call", result); > } catch (error) { > emitter.error(error, { tool: "api_call" }); > throw error; > } > ``` *** ## API Reference > [card] [TraceSink](https://praison.ai/docs/sdk/reference/typescript/classes/TraceSink.md) > > Trace sink base class > [card] [ContextTraceEmitter](https://praison.ai/docs/sdk/reference/typescript/classes/ContextTraceEmitter.md) > > Trace event emitter *** ## Best Practices > [accordion] Use structured trace IDs > > Include `traceId` and `spanId` for distributed tracing across services. > [accordion] Buffer events for performance > > Batch events before sending to external services to reduce overhead. > [accordion] Use NoOpSink in production > > Disable tracing in production unless needed to avoid performance impact. *** ## Related > [card] [Observability](https://praison.ai/docs/js/observability.md) > > Full observability integration > [card] [Telemetry](https://praison.ai/docs/js/telemetry.md) > > Telemetry collection This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.