LiveKit Tracing

Enhanced observability for LiveKit agents using the Cekura SDK

Using a coding agent? Paste this prompt directly in your LiveKit agent codebase to jumpstart your Cekura integration.

Overview

LiveKit Tracing provides deep observability into your LiveKit agent’s performance by integrating the Cekura SDK directly into your agent code. This integration significantly enhances the information available in the Cekura platform for end-to-end visibility over agent execution.

What you get:

• Complete conversation transcripts with full message history
• Tool/function calls with inputs and outputs
• Detailed performance metrics (STT, TTS, LLM, End-of-Utterance)
• Session logs captured automatically from your application
• Mock tools support for testing with predictable tool responses
• Dual-channel audio recording for monitoring production calls
• LiveKit job and room metadata

Video Tutorial

Prerequisites

• A Cekura account with an API key
• A LiveKit agent project

Setup

Testing

Use this setup in your test agents while running simulation calls from the Cekura platform.

1. Install the Cekura SDK

   Python

   pip install "cekura[livekit]>=1.6.4"
   

   JavaScript

   npm install @cekura/livekit@1.0.0-rc.1
   
2. Integrate the SDK in your LiveKit agent

   Add the Cekura tracer to your LiveKit agent’s entrypoint:

   Python

   import os
   from livekit import agents
   from cekura.livekit import LiveKitTracer
   
   # Initialize Cekura tracer
   cekura = LiveKitTracer(
       api_key=os.getenv("CEKURA_API_KEY"),
       agent_id=123  # Your agent ID from Cekura dashboard
   )
   
   @server.rtc_session(agent_name="my_agent")
   async def entrypoint(ctx: agents.JobContext):
       assistant = YourAssistant()
       session = agents.AgentSession(...)
   
       # Track session with automatic tool injection and export
       await cekura.track_session(ctx, session, assistant)
   
       await session.start(room=ctx.room, agent=assistant)
   

   JavaScript

   import { defineAgent, voice } from '@livekit/agents';
   import type { JobContext } from '@livekit/agents';
   import { LiveKitTracer } from '@cekura/livekit';
   
   // Initialize Cekura tracer
   const cekura = new LiveKitTracer({
     apiKey: process.env.CEKURA_API_KEY || '',
     agentId: 123, // Your agent ID from Cekura dashboard
   });
   
   export default defineAgent({
     entry: async (ctx: JobContext) => {
       const agent = new YourAssistant();
       const session = new voice.AgentSession({ /* stt, llm, tts, vad */ });
   
       // Track session with automatic tool injection and export
       await cekura.trackSession(ctx, session, agent);
   
       await session.start({ room: ctx.room, agent });
     },
   });
   

   What this does:

   • Captures transcripts, tool calls, metrics, and session logs
   • Automatically injects mock tools configured in Cekura
   • Automatically configures chat/text mode when running text-based tests
   • Exports data to Cekura for test analysis
3. Configure LiveKit provider and enable tracing

   Navigate to your agent settings in the Cekura dashboard, select LiveKit as the provider, and enable tracing:

   

   Required configuration:

   • LiveKit API Key: Your LiveKit API key
   • LiveKit API Secret: Your LiveKit API secret
   • LiveKit URL: Your LiveKit server URL (e.g., wss://your-server.livekit.cloud)
   • Agent Name: The specific agent name to dispatch in LiveKit

   Optional configuration:

   • LiveKit Config (JSON): Additional room configuration parameters (accessible in agent code via get_simulation_data())

   Testing connection types:

   

   Configure at least one connection type for voice-based testing:

   • WebRTC: Direct LiveKit room connection using the credentials configured above
   • Telephony: Phone-based testing if your LiveKit agent is connected to a phone system (requires Contact Number)

   For text-based testing:

   • Chat: Select LiveKit to enable chat-based testing (uses the same WebRTC configuration, no additional setup required)
4. Run tests

   Run tests using your preferred connection type:

   • WebRTC: Select WebRTC under Voice connections in the Configure Run dialog for WebRTC-based testing
   • Telephony: Select Telephony under Voice connections for phone-based testing
   • Chat: Select a chat connection for text-based testing

   
5. Analyze the call

   Navigate to the Runs section to view your test results with enhanced data including transcripts, tool calls, session logs, and detailed performance metrics.

Observability

Use this setup in your production agents for monitoring live calls with audio recording.

1. Install the Cekura SDK

   Python

   pip install "cekura[livekit]>=1.6.4"
   

   JavaScript

   npm install @cekura/livekit@1.0.0-rc.1
   
2. Integrate the SDK in your LiveKit agent

   Add the Cekura tracer to your LiveKit agent’s entrypoint:

   Python

   import os
   from livekit import agents
   from cekura.livekit import LiveKitTracer
   
   # Initialize Cekura tracer
   cekura = LiveKitTracer(
       api_key=os.getenv("CEKURA_API_KEY"),
       agent_id=123  # Your agent ID from Cekura dashboard
   )
   
   @server.rtc_session(agent_name="my_agent")
   async def entrypoint(ctx: agents.JobContext):
       assistant = YourAssistant()
       session = agents.AgentSession(...)
   
       # Observe session with audio recording and metrics
       await cekura.observe_session(ctx, session)
   
       await session.start(room=ctx.room, agent=assistant)
   

   JavaScript

   import { defineAgent, voice } from '@livekit/agents';
   import type { JobContext } from '@livekit/agents';
   import { LiveKitTracer } from '@cekura/livekit';
   
   // Initialize Cekura tracer
   const cekura = new LiveKitTracer({
     apiKey: process.env.CEKURA_API_KEY || '',
     agentId: 123, // Your agent ID from Cekura dashboard
   });
   
   export default defineAgent({
     entry: async (ctx: JobContext) => {
       const agent = new YourAssistant();
       const session = new voice.AgentSession({ /* stt, llm, tts, vad */ });
   
       // Observe session with audio recording and metrics
       await cekura.observeSession(ctx, session);
   
       await session.start({ room: ctx.room, agent });
     },
   });
   

   What this does:

   • Captures transcripts, tool calls, metrics, and session logs
   • Records dual-channel audio (agent + user) for analysis
   • Exports data to Cekura observability endpoint
3. Configure LiveKit provider and credentials

   Navigate to your agent settings in the Cekura dashboard, select LiveKit as the provider:

   

   Required configuration for audio recording:

   • LiveKit API Key: Your LiveKit API key
   • LiveKit API Secret: Your LiveKit API secret
   • LiveKit URL: Your LiveKit server URL (e.g., wss://your-server.livekit.cloud)
   • Agent Name: The specific agent name to dispatch in LiveKit

   All LiveKit credentials are required to enable audio egress recording for production calls.

4. Monitor production calls

   Once configured, all production calls will automatically appear in the Calls section of your Cekura dashboard.

Enhanced Data in Cekura UI

With tracing enabled, you’ll see enriched information in the Cekura platform:

The run now displays:

• Room Session ID: Visible in the call provider ID field, allowing you to correlate Cekura test runs with specific LiveKit sessions
• Complete Transcript: Full conversation history from the LiveKit agent, including tool/function call requests and responses
• OpenTelemetry Traces: User and agent turns with STT, LLM, tool, and TTS spans
• Provider Call Data: Detailed metadata accessible in the run details, including job information, room configuration, session logs, and raw performance metrics

Provider Call Data contains the following information:

• Job Information: Job ID, room name, participant details, and agent dispatch metadata
• Room Information: Room configuration, participant count, session duration, and connection details
• Session Logs: Captured agent session logs with timestamps, log levels, and messages for debugging
• Raw Metrics:
  • STT (Speech-to-Text): Latency, duration, and transcription timing
  • TTS (Text-to-Speech): Generation time and audio synthesis metrics
  • LLM: Token usage, response time, and inference latency
  • EOU (End-of-Utterance): Detection timing and accuracy
• Custom Metadata: Additional metadata passed to the SDK via the metadata parameter

OpenTelemetry Tracing

The Python SDK automatically exports LiveKit’s native OpenTelemetry spans to Cekura. The trace is correlated with the simulation run created by track_session() or the call log created by observe_session(), so the full execution timeline is available alongside the transcript, metrics, and, in observability mode, the recording.

OpenTelemetry trace export requires Cekura Python SDK 1.5.2 or later. Call track_session() or observe_session() before session.start() so tracing is configured before LiveKit starts the agent session.

Trace Structure

Each call produces a hierarchical trace containing the LiveKit spans emitted during user and agent turns:

Agent session
├── User turn
│   ├── User speaking
│   └── STT / end-of-utterance detection
└── Agent turn
    ├── LLM
    ├── Tool
    ├── TTS
    └── Agent speaking

The trace view groups LiveKit’s internal LLM and TTS spans into readable operations while retaining their timing and attributes. Incomplete trailing turns are also shown when a call ends before the next full turn completes.

How It Works

No separate LiveKit tracing configuration is required. When track_session() or observe_session() is called, the SDK:

1. Configures LiveKit’s OpenTelemetry provider using your Cekura API key and agent ID
2. Exports spans to Cekura’s OTLP/gRPC endpoint
3. Captures the agent-session trace ID and sends it with the run or call-log payload
4. Flushes pending spans when the LiveKit job shuts down

The endpoint can be overridden when using a custom Cekura environment:

cekura = LiveKitTracer(
    api_key=os.getenv("CEKURA_API_KEY"),
    agent_id=123,
    otel_endpoint="https://otel.cekura.ai",
)

Disabling OTel Traces

To disable OTel trace export entirely:

cekura = LiveKitTracer(
    api_key=os.getenv("CEKURA_API_KEY"),
    agent_id=123,
    enable_otel_traces=False,
)

When disabled, no OTel provider is configured and no traces are exported. All other SDK features continue to work normally.

Automatic Chat Mode Support

The SDK automatically handles chat/text mode configuration when you run scenarios using “Run with Text” — no code changes required.

When you run a text-based test, the SDK automatically patches your session to disable audio processing, enabling pure text-based interactions with your agent. This provides:

• Targeted testing of your agent’s conversational logic without audio overhead
• Cost savings by eliminating STT/TTS provider costs and reducing Cekura credit usage
• Faster simulations compared to voice-based tests

Your track_session() / trackSession() integration works seamlessly for both voice and text modes.

Using Mock Tools with LiveKit Tracing

The SDK supports mock tools, allowing you to test your agent with predictable tool responses. This is useful for creating reproducible test scenarios without relying on live external services.

To use mock tools:

1. Create mock tools in Cekura: Set up your mock tool configurations in the Cekura dashboard. See the Mock Tools guide for detailed instructions.

2. SDK handles the rest: Once mock tools are configured, the SDK automatically routes tool calls to Cekura’s mock endpoints during testing - no additional code changes needed.

3. Test with predictable data: Your agent will receive the mock responses you configured, making it easy to test specific scenarios and edge cases.

Best Practices

1. Use the right method for your environment: Use track_session() / trackSession() in your test/UAT environments for simulation testing with mock tools. Use observe_session() / observeSession() in your production environment for monitoring live calls with audio recording.

2. Use environment variables for credentials: Don’t hardcode API keys in your code

3. Keep the SDK updated: Periodically upgrade to the latest version for new features.

   Python

   pip install --upgrade cekura[livekit]
   

   JavaScript

   npm install @cekura/livekit@latest
   

4. Review tool calls regularly: Add the predefined metric Tool Call Success to your evaluators

SDK Reference

LiveKitTracer Initialization

Python

from cekura.livekit import LiveKitTracer

cekura = LiveKitTracer(
    api_key="your_api_key",         # Required: Your Cekura API key
    agent_id=123,                   # Required: Agent ID from dashboard
    host="https://api.cekura.ai",   # Optional: Custom API host
    enabled=True,                   # Optional: Enable/disable tracer
    otel_endpoint="https://otel.cekura.ai",  # Optional: Custom OTel endpoint
    enable_otel_traces=True         # Optional: Enable/disable OTel export
)

JavaScript

import { LiveKitTracer } from '@cekura/livekit';

const cekura = new LiveKitTracer({
  apiKey: 'your_api_key',         // Required: Your Cekura API key
  agentId: 123,                   // Required: Agent ID from dashboard
  host: 'https://api.cekura.ai',  // Optional: Custom API host
  enabled: true,                  // Optional: Enable/disable tracer
});

track_session()

Tracks simulation/test calls with automatic mock tool injection and chat mode support. Collects transcripts, tool calls, session logs, and metrics.

Python

await cekura.track_session(
    ctx,               # Required: LiveKit JobContext
    session,           # Required: LiveKit AgentSession
    agent,             # Optional: Agent instance for mock tool injection
    capture_logs=True, # Optional: Capture session logs (default: True)
    **metadata         # Optional: Custom metadata
)

JavaScript

await cekura.trackSession(
  ctx,         // Required: LiveKit JobContext
  session,     // Required: LiveKit AgentSession
  agent,       // Optional: Agent instance for mock tool injection
  metadata,    // Optional: Custom metadata object
  captureLogs, // Optional: Capture session logs (default: true)
);

Environment variables:

• CEKURA_TRACING_ENABLED="false": Disable tracking entirely
• CEKURA_MOCK_TOOLS_ENABLED="false": Disable only mock tool injection

observe_session()

Monitors production calls with dual-channel audio recording. Collects transcripts, tool calls, session logs, and metrics. Requires LiveKit credentials configured in Cekura.

Python

await cekura.observe_session(
    ctx,               # Required: LiveKit JobContext
    session,           # Required: LiveKit AgentSession
    capture_logs=True, # Optional: Capture session logs (default: True)
    **metadata         # Optional: Custom metadata
)

JavaScript

await cekura.observeSession(
  ctx,         // Required: LiveKit JobContext
  session,     // Required: LiveKit AgentSession
  metadata,    // Optional: Custom metadata object
  captureLogs, // Optional: Capture session logs (default: true)
);

Environment variables:

• CEKURA_OBSERVABILITY_ENABLED="false": Disable observability entirely

get_simulation_data()

Extracts simulation data populated by Cekura when running simulation calls from the platform. Returns an empty object for phone-based calls.

Python

await ctx.connect()  # Must be called first

simulation_data = cekura.get_simulation_data(
    ctx    # Required: LiveKit JobContext
)

JavaScript

await ctx.connect(); // Must be called first

const simulationData = cekura.getSimulationData(
  ctx, // Required: LiveKit JobContext
);

Returns: Object with simulation metadata:

Python

{
    "scenario_id": 123,              # Scenario being tested
    "run_id": 456,                   # Current run ID
    "test_profile_data": {           # Test profile data
        "customer_name": "John Doe",
        "account_number": "ACC-12345"
    },
    "additional_config": {           # LiveKit config from agent settings
        "sample_key": "sample_value"
    }
}

JavaScript

{
  scenario_id: 123,                  // Scenario being tested
  run_id: 456,                       // Current run ID
  test_profile_data: {               // Test profile data
    customer_name: 'John Doe',
    account_number: 'ACC-12345',
  },
  additional_config: {               // LiveKit config from agent settings
    sample_key: 'sample_value',
  },
}

This data is ONLY available when using Option 2 (Automated LiveKit Testing) — running tests via WebRTC connection. Phone-based calls (Option 1) will return an empty object.

Next Steps

• Set up mock tools for testing with predictable tool responses
• Create custom metrics to evaluate based on provider call data
• Perform load testing with your LiveKit agent
• Explore predefined metrics