Traces

Overview

Roark supports OpenTelemetry (OTel) tracing. Send your OTel trace data to Roark to see what happens under the hood of your Voice AI agent, debug latency, inspect tool usage and external API calls, and correlate call execution with your backend traces.

Features

LLM traces per call — View LLM spans, tool calls, and model invocations directly on the call detail page. Each call’s Tracing tab shows the full trace tree for that conversation, so you can quickly pinpoint where latency or failures occurred.
Central trace explorer — See all traces in one place. Filter by time range, custom tags, or search by span name and attributes. Use this to spot patterns across calls, compare runs, and troubleshoot recurring issues.

Roark Traces view showing agent turns with STT, LLM, and TTS spans

Endpoint and Protocol

Requirement	Details
Protocol	OTLP over HTTPS only
Endpoint	Send traces to Roark’s OTel endpoint (see examples below)
OTel traces URL	`https://api.roark.ai/v1/traces`
Authorization	Required. Send `Authorization: Bearer YOUR_ROARK_API_KEY` in the request headers.
Role	Roark acts as an OTel Collector

All trace ingestion requests require authentication. Generate an API key in your Roark dashboard and use it in the Authorization: Bearer YOUR_ROARK_API_KEY header.

Setup Guide

Get an API key

Generate an API key in your Roark dashboard. Trace ingestion requires authentication via the Authorization: Bearer YOUR_ROARK_API_KEY header. Create an API key →

Create your integration

Set up your voice platform integration first. See the LiveKit and VAPI integrations guide for step-by-step setup.

LiveKit
VAPI
Pipecat
Custom Integration

Instrument your LiveKit agent with OpenTelemetry and export traces to Roark. Configure your tracer with the livekit.room.id resource attribute — this is how Roark links your LiveKit room to its traces and shows them on the call detail page.Install the required packages:

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http livekit-agents

Example: a simple LiveKit Agent entrypoint with OTel exporting to Roark:

import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from livekit.agents import AgentServer, JobContext, cli


def setup_roark_tracer(room_id: str):
    """Configure OTel to export traces to Roark with livekit.room.id for call correlation."""
    resource = Resource.create({
        "livekit.room.id": room_id,  # Required: Roark uses this to link traces to the call
        "roark.skip": False,         # Optional: set to True to filter out these traces
    })
    provider = TracerProvider(resource=resource)
    provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                endpoint="https://api.roark.ai/v1/traces",
                headers={"Authorization": f"Bearer {os.environ['ROARK_API_KEY']}"},
            )
        )
    )
    trace.set_tracer_provider(provider)


server = AgentServer()


@server.rtc_session(agent_name="my-agent")
async def entrypoint(ctx: JobContext):
    room_id = ctx.job.room.sid
    setup_roark_tracer(room_id)
    await ctx.connect()

    tracer = trace.get_tracer(__name__)
    with tracer.start_as_current_span("agent-session"):
        # Your agent logic here
        pass


if __name__ == "__main__":
    cli.run_app(server)

Resource attributes:

Attribute	Required	Description
`livekit.room.id`	Yes	The LiveKit room SID (`ctx.job.room.sid`). Roark uses this to link traces to the corresponding call.
`roark.skip`	No	Set to `true` to tell Roark to filter out traces for this room. Useful for skipping test or internal calls.

If you’re also using the LiveKit webhook integration, you can set roark.skip in both room metadata and OTel resource attributes to skip both call processing and trace ingestion.

For any other platform, use the OTLP HTTP trace exporter and point it to Roark’s OTel endpoint. Include the required Authorization: Bearer YOUR_ROARK_API_KEY header and attach the required resource attributes.

TypeScript (Node.js)
Go
Python

npm install @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { Resource } from "@opentelemetry/resources";

const exporter = new OTLPTraceExporter({
  url: "https://api.roark.ai/v1/traces",
  headers: { Authorization: `Bearer ${process.env.ROARK_API_KEY}` },
});

const resource = new Resource({
  "roark.project.tag.env": process.env.ROARK_ENV ?? "production",
});

const provider = new NodeTracerProvider({ resource });
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
provider.register();

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
  go.opentelemetry.io/otel/sdk/trace

package main

import (
	"context"
	"os"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

func initTracer() (func(context.Context) error, error) {
	exporter, err := otlptracehttp.New(context.Background(),
		otlptracehttp.WithEndpoint("api.roark.ai"),
		otlptracehttp.WithURLPath("/v1/traces"),
		otlptracehttp.WithHeaders(map[string]string{
			"Authorization": "Bearer " + os.Getenv("ROARK_API_KEY"),
		}),
	)
	if err != nil {
		return nil, err
	}

	res, err := resource.New(context.Background(),
		resource.WithAttributes(
			semconv.ServiceName("my-voice-agent"),
			attribute.String("roark.project.id", "your-project-id"),
			attribute.String("roark.project.tag.env", "production"),
		),
	)
	if err != nil {
		return nil, err
	}

	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(res),
	)
	otel.SetTracerProvider(tp)
	return tp.Shutdown, nil
}

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

exporter = OTLPSpanExporter(
    endpoint="https://api.roark.ai/v1/traces",
    headers={"Authorization": f"Bearer {os.getenv('ROARK_API_KEY')}"},
)

resource = Resource(attributes={
    "roark.project.tag.env": os.getenv("ROARK_ENV", "production"),
})

provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

You’re now ready to send traces to Roark and debug your Voice AI calls. You’ll be able to view them on the Traces page and directly within each call’s detail page.

What’s Next

Live monitoring

View and debug active calls

Metrics & reports

Define and analyze call metrics

Dashboards

Build observability views

API reference

Explore Roark API endpoints

Getting Started

Observability

Metrics

Simulations

Integrations

SDKs & Libraries

Resources

Overview

Features

Endpoint and Protocol

Setup Guide

What’s Next

Live monitoring

Metrics & reports

Dashboards

API reference

Getting Started

Observability

Metrics

Simulations

Integrations

SDKs & Libraries

Resources

​Overview

​Features

​Endpoint and Protocol

​Setup Guide

​What’s Next

Live monitoring

Metrics & reports

Dashboards

API reference

Overview

Features

Endpoint and Protocol

Setup Guide

What’s Next