Connect your traces

Use this guide when you are ready to connect a traced service or agent to TraceFast. Start with one simple path, confirm the first session looks right, then expand from there.

The TraceFast collector accepts OTLP over HTTP and OTLP over gRPC. OTLP HTTP is the easiest first test because the endpoint is explicit and easy to verify.

Choose your collector address

If you are using the hosted app, send traces to the hosted collector.

• OTLP HTTP hosted: https://collector.tracefast.dev/v1/traces
• OTLP gRPC hosted: collector.tracefast.dev:4317

Send your project key

Every trace request must include your project key in the x-tracefast-api-key header. OTLP gRPC exporters send the same value as gRPC metadata.

POST /v1/traces
x-tracefast-api-key: wk_live_...
Content-Type: application/x-protobuf

Choose the names you want to see

Set these resource attributes before you send traces so your sessions are easy to recognize in TraceFast.

• service.name is the name you want to see in TraceFast, such as hotel-interview-agent.
• deployment.environment.name is the environment name you want to see, such as development, staging, or production.

LiveKit example for OTLP HTTP

If you are using a LiveKit Python agent, this snippet works with the same setup used in livekit_agent_example.py. It sends traces to the hosted TraceFast collector over OTLP HTTP.

import os

from livekit.agents.telemetry import set_tracer_provider
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

provider = TracerProvider(
    resource=Resource.create(
        {
            "service.name": "hotel-interview-agent",
            "deployment.environment.name": "development",
            "voice.runtime.name": "livekit",
        }
    )
)

provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://collector.tracefast.dev/v1/traces",
            headers={"x-tracefast-api-key": os.environ["TRACEFAST_API_KEY"]},
        )
    )
)

set_tracer_provider(provider)

Connect with OTLP gRPC

If your exporter already uses OTLP gRPC, keep the same project key and the same resource attributes.

• Use collector.tracefast.dev:4317 for the hosted collector.
• Send x-tracefast-api-key as request metadata.

Check the first session

After you connect the exporter, confirm the first real run inside the app.

1. Run one real request, conversation, or job.
2. Open the project dashboard.
3. Open Sessions, and find the new session.
4. Open the session, and confirm the conversation timeline, trace, issues, and cost sections look reasonable.

If the cost section shows unmatched models, add a project pricing override in Settings.