Agent traces

Embrasure accepts OpenTelemetry traces over OTLP/HTTP at https://api.embrasure.ai/v1/traces and keeps them in your workspace's TraceDB database. Each trace becomes one run with its model calls, tool calls, timing, tokens and outcome, and you can ask about runs in chat.

Before you start

In Embrasure, open Sources, then Context → Add context → Agent traces, and:

1. Start TraceDB. A workspace owner or admin starts the workspace's database once. It takes a few minutes.
2. Get an API key. Copy prompt downloads one for your coding agent. To set up tracing yourself, open or set up tracing manually and select Create API key. Editors, admins and owners can create one. It's a personal access token with write access to the workspace that acts as you and expires in 90 days; revoke it under Personal access tokens. Embrasure shows it once, with the variables an OpenTelemetry SDK reads, and can download them as embrasure-traces.env:

EMBRASURE_TRACES_TOKEN=dpt_...
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.embrasure.ai/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20dpt_...

Keep the key on your servers, out of chat and out of git.

Set up with a coding agent

Copy prompt on the Agent traces page copies a prompt for Claude Code, Cursor, Codex or another coding agent and downloads embrasure-traces.env. The prompt points the agent at this page and at the file, so the key never goes into the chat.

Instructions for coding agents

If you're a coding agent adding Embrasure tracing to an application:

1. Find embrasure-traces.env in the user's Downloads folder. If it isn't there, or there are several, ask the user which file to use. Never print its contents or ask the user to paste the key into chat.
2. Load its variables the way the application already loads secrets (a .env file the app reads, a secrets manager, or deployment settings). Keep the file and the key out of git, and check with the user before overwriting existing configuration.
3. Add instrumentation that fits the framework, from Set up by hand. Export over OTLP/HTTP to OTEL_EXPORTER_OTLP_TRACES_ENDPOINT with the Authorization header; gRPC isn't accepted.
4. Set service.name to the agent's name, and name each agent run (functionId in the AI SDK).
5. Flush the tracer provider before a short-lived process exits, such as a serverless function or a script.
6. Tell the user how to run the application once, so the first trace arrives in Embrasure.

Set up by hand

Each setup below reads the key from EMBRASURE_TRACES_TOKEN.

AI SDK

For AI SDK 7 in Next.js, install the packages and add instrumentation.ts at the project root:

npm install @vercel/otel @opentelemetry/api @ai-sdk/otel

import { OpenTelemetry } from "@ai-sdk/otel";
import { OTLPHttpProtoTraceExporter, registerOTel } from "@vercel/otel";
import { registerTelemetry } from "ai";

export function register() {
  registerOTel({
    serviceName: "support-agent",
    traceExporter: new OTLPHttpProtoTraceExporter({
      url: "https://api.embrasure.ai/v1/traces",
      headers: { Authorization: `Bearer ${process.env.EMBRASURE_TRACES_TOKEN}` },
    }),
  });
  registerTelemetry(new OpenTelemetry());
}

Name the agent on each call:

const result = await generateText({
  model,
  tools,
  prompt,
  telemetry: { functionId: "support-agent" },
});

On AI SDK 6, leave out @ai-sdk/otel and registerTelemetry, and pass experimental_telemetry: { isEnabled: true, functionId } to each call instead.

OpenAI Agents SDK

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http \
  openinference-instrumentation-openai-agents

Before your agent starts:

import os

from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
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": "support-agent"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://api.embrasure.ai/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['EMBRASURE_TRACES_TOKEN']}"},
)))
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

LangChain, LlamaIndex and CrewAI have OpenInference instrumentors too: install theirs and pass the same provider.

Any OpenTelemetry SDK

Set the standard variables, as embrasure-traces.env does. The header's space is URL-encoded:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.embrasure.ai/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20${EMBRASURE_TRACES_TOKEN}"
export OTEL_SERVICE_NAME="support-agent"

Any exporter that sends OTLP over HTTP, protobuf or JSON, works, including an OpenTelemetry Collector's otlphttp exporter.

What Embrasure keeps

Each trace becomes one run. Model calls are recorded as chat and tool calls by the tool's name, each with its status, duration, tokens and model. The run keeps its agent, service, user and session.

Embrasure reads OpenTelemetry's GenAI attributes, and the AI SDK's, OpenInference's, OpenLLMetry's, Langfuse's, MLflow's and LangSmith's names for the same things. Other attributes are kept as they arrive, including prompts and outputs if your instrumentation records them, and every member of the workspace can read them. To keep only the mapped fields, send the header X-Embrasure-Trace-Unmapped: drop.

Troubleshooting

If nothing arrives and there's no error, check that the exporter uses HTTP rather than gRPC (port 4317), and that the process flushes its spans before it exits.