Overview
Roark supports OpenTelemetry (OTel) tracing. Send your OTel trace data to Roark to see every agent turn—including how STT, LLM, and TTS are used in each turn—debug latency, inspect tool usage and external API calls, and correlate call execution with your backend traces.
Roark acts as an OTEL Collector: you send traces to our endpoint, and we ingest, store, and surface them in the Roark UI alongside your call data.
Protocol: We support OTLP over HTTPS only. Configure your application to use the OTLP HTTP exporter and point it to Roark’s OTel endpoint.
Integrations
LiveKit
Vapi
Pipecat
Custom Integration
For LiveKit agents, configure the OpenTelemetry SDK to export traces to Roark alongside your agent setup. This gives you full visibility into your agent’s execution, including tool calls, LLM latency, and external API requests.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
def configure_roark_tracing():
"""Call this before starting your LiveKit agent."""
exporter = OTLPSpanExporter(
endpoint="https://api.roark.ai/v1/otel/v1/traces",
headers={"Authorization": f"Bearer {os.getenv('ROARK_API_KEY')}"},
)
resource = Resource(attributes={
"roark.project.id": os.getenv("ROARK_PROJECT_ID", "your-project-id"),
"roark.project.tag.env": os.getenv("ROARK_ENV", "production"),
})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
# Initialize tracing before your agent starts
configure_roark_tracing()
If you have a Vapi integration set up in Roark, tracing works automatically—no additional configuration is needed.Roark automatically collects OpenTelemetry trace data whenever call data is synced from Vapi. Each time a new call is synced, we ingest any OTel data associated with that call so you can view traces alongside the call in Roark—without configuring a separate OTLP exporter for Vapi-originated traffic.Use Observability → Traces or the Tracing tab on a call to see them.Make sure Public Logs are enabled in your Vapi dashboard. Roark requires public log access to ingest trace data from Vapi calls.
Pipecat tracing support is coming soon. Stay tuned for updates.
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/otel/v1/traces',
headers: { 'Authorization': `Bearer ${process.env.ROARK_API_KEY}` },
});
const resource = new Resource({
'roark.project.id': process.env.ROARK_PROJECT_ID ?? 'your-project-id',
'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/otel/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/otel/v1/traces",
headers={"Authorization": f"Bearer {os.getenv('ROARK_API_KEY')}"},
)
resource = Resource(attributes={
"roark.project.id": os.getenv("ROARK_PROJECT_ID", "your-project-id"),
"roark.project.tag.env": os.getenv("ROARK_ENV", "production"),
})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
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/otel/v1/traces |
| Authorization | Required. Send Authorization: Bearer YOUR_ROARK_API_KEY in the request headers. |
| Role | Roark acts as an OTel Collector |
/v1/traces) are appended by the SDK.
Required and Optional Attributes
Configure these resource attributes so Roark can associate traces with your project and environment:
| Attribute | Required | Description |
|---|
roark.project.id | Yes | Your Roark project ID. Required for traces to appear in the correct project. |
roark.project.tag.env | Optional (not recommended to omit) | Environment tag (e.g. production, staging). Optional; not recommended to omit—set it so you can filter traces by environment. |
roark.project.id is required. Traces without this attribute cannot be associated with your project and may not appear correctly.
roark.project.tag.env is optional; we do not recommend omitting it. Set it so you can filter traces by environment (e.g. production vs staging).
Where Traces Are Visible
After sending traces to Roark, you can view them in two places:
Browse and search all traces for your project (and optionally filter by environment).
Call Detail → Tracing tab
For a specific call, open the call detail view and use the Tracing tab to see traces correlated with that call.
Benefits
- See what happens under the hood — Understand the full execution path of your Voice AI agent, from entrypoint to tool calls and external APIs.
- Debug latency — Identify slow operations and bottlenecks using span timings and the trace timeline.
- Inspect tool usage and external API calls — See which tools and APIs were invoked during a call and how long they took.
- Correlate call execution with backend traces — Link Roark call data to your own services by sending traces from your backend to the same project and environment.
- Production visibility — Run OTel in production and use
roark.project.tag.env (e.g. production) to keep production traces organized and filterable.
Summary
| Topic | Details |
|---|
| Protocol | OTLP over HTTPS only |
| Endpoint (traces) | https://api.roark.ai/v1/otel/v1/traces |
| Authorization | Required: Authorization: Bearer YOUR_ROARK_API_KEY |
| Role | Roark acts as an OTel Collector |
| Required attribute | roark.project.id |
| Optional attribute | roark.project.tag.env (optional; not recommended to omit) |
| Where to view | Observability → Traces; Call Detail → Tracing tab |
