Quick Start

These examples use the hosted Trace Flow service. An account with access is required.

Trace Flow Analyst, the in-app chat for investigating your analytics, requires an active Pro subscription and is not available on Hobby.

This guide connects model API traffic to Trace Flow. Gateway requests produce LLM spans and event metadata. Add W3C trace context or export application spans over OTLP when you want those LLM spans joined to the rest of an application trace.

To observe the coding agent itself, install the separate coding-agent collector. If you want an agent to wire your application's model calls through the gateway, give it /agents.md.

1) Add your env vars

Keep your upstream provider key exactly as you already do, then add your Trace Flow key:

export TRACE_FLOW_API_KEY="your-trace-flow-key"
export OPENAI_API_KEY="your-provider-key"
export OPENAI_MODEL="your-openai-model"

2) Install SDK dependencies

npm install ai @ai-sdk/openai

3) Configure your provider to use the Trace Flow gateway

Use your normal provider API key and add your Trace Flow API key in headers.

import { createOpenAI } from '@ai-sdk/openai';

const openai = createOpenAI({
  baseURL: 'https://gateway.trace-flow.dev/openai/v1',
  apiKey: process.env.OPENAI_API_KEY,
  headers: {
    'X-Trace-Flow-Api-Key': process.env.TRACE_FLOW_API_KEY,
  },
});

4) Send requests as normal

import { generateText } from 'ai';

const result = await generateText({
  model: openai(process.env.OPENAI_MODEL!),
  prompt: 'Plan a weekend trip to Portland.',
});

5) Link requests to your app traces

To stitch LLM calls into your existing trace hierarchy, pass W3C trace context headers.

import { trace, context } from '@opentelemetry/api';
import { generateText } from 'ai';

const parentSpan = tracer.startSpan('user-request');
const ctx = parentSpan.spanContext();

const result = await generateText({
  model: openai(process.env.OPENAI_MODEL!),
  prompt: userMessage,
  headers: {
    traceparent: `00-${ctx.traceId}-${ctx.spanId}-01`,
    baggage: 'operation=chat,user_id=user_123',
  },
});

parentSpan.end();

Required headers

What can be tracked

• Request and response bodies when recording is enabled and body storage is not omitted
• Token usage reported by the provider, including cached or reasoning tokens where available
• Timing metrics, including time to first token for streaming responses
• Model/provider metadata and finish reason
• Errors and status codes

Next docs

• AI Agents
• Coding-Agent Collector
• SDK Reference
• OpenTelemetry

Self-hosted deployments

For your own deployment, replace the hosted endpoints and credentials in these examples with those from your installation. Requests and captured activity are sent to the deployment you configure. Use synthetic data when testing your setup.