Integrations
Traces and sessions
See an agent run as one trace with a tree of steps. Add headers to the calls you already make, send your own spans with OpenTelemetry or a Langfuse SDK, or both.
How a run becomes a trace
An agent run is many requests: model calls, tool calls between them, and subagents. Observability shows each run as one trace and one session. Three sources add up and never replace each other: headers on your model calls, tool calls and subagents we infer from your traffic, and spans you send yourself. Read the result with the Request log API or the trace tools.
1. Headers on the calls you already make
No SDK is needed. Add any of these to the model calls that go through the gateway. A header always wins over the same fact in the body. Claude Code and Codex need nothing: their own session headers already link their turns and subagents.
| Fact | Headers | Or in the request body |
|---|---|---|
| Session id | X-Explabs-Session-Id, Helicone-Session-Id, x-session-id, x-litellm-session-id, baggage: gen_ai.conversation.id=... | metadata.session_id, metadata["gen_ai.conversation.id"] |
| Parent session | X-Explabs-Parent-Session-Id, x-parent-session-id | metadata.parent_session_id |
| Session name | X-Explabs-Session-Name, Helicone-Session-Name | metadata.session_name |
| Place in your trace | traceparent (W3C) | metadata.traceparent |
| Trace name | X-Explabs-Trace-Name | metadata.trace_name |
| Step name | X-Explabs-Span-Name, X-Explabs-Step-Name, X-Explabs-Observation-Name | metadata.span_name |
| Step path, like /plan/research/search-1 | X-Explabs-Step-Path, X-Explabs-Session-Path, Helicone-Session-Path | metadata.step_path |
| End user | X-Explabs-User-Id, Helicone-User-Id | metadata.end_user, metadata.user_id, safety_identifier, user |
| Tags | X-Explabs-Tags: {"env":"prod"} | metadata.tags (an object, a JSON object string, or a list of "key:value") |
curl https://api.experientiallabs.ai/v1/chat/completions \-H "Authorization: Bearer $EXPLABS_API_KEY" \-H "X-Explabs-Session-Id: run-42" \-H "X-Explabs-Step-Path: /plan/research/search-1" \-H 'X-Explabs-Tags: {"env":"prod","feature":"support"}' \-H "Content-Type: application/json" \-d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"hi"}]}'
- Limits: ids up to 256 characters, names up to 200, a path up to 512 characters and 32 steps, and 16 tags. A body value that does not fit is skipped, and the request is never refused for it. A malformed
X-Explabs-Tagsheader is still a 400. - Every request has a session. If you send none, it is filed under the conversation we recognize, or else under its own trace.
- Every gateway request is one span. Its span id comes from the request id, so it is the same in Observability, in every API answer and in an export to your own Langfuse. A call without
traceparentstarts its own trace.
2. Tool calls and subagents we infer
When a response asks for tool calls and the next request carries their results, we add one tool span per call with the name, arguments, result and a duration equal to the gap between the two. These spans are marked inferred (inf: 1 in an API answer) because the gap also holds any other work your code did. Subagents come from Claude Code's agent id or a nested traceparent. Inference runs only on requests whose content is stored. When you send your own tool spans, yours are the truth.
3. Your own spans
Spans you send land in the same trace as our model spans when they share the trace id. Our spans add exact tokens, cost and fallback detail to yours and never replace them. Use your organization's xpl_ key. Both ways in take it.
| Method and path | What it takes |
|---|---|
| POST /v1/traces | OTLP over HTTP, protobuf (application/x-protobuf) or JSON, optionally gzip. |
| POST /api/otlp/v1/traces | The same, for setups that only route /api paths. |
| POST /api/public/otel/v1/traces | The same, at Langfuse's OpenTelemetry path (Langfuse Python SDK v3). |
| POST /api/public/ingestion | The Langfuse batch ingestion API. Answers 207 with successes and errors for each event, as Langfuse does. |
| GET /api/public/projects | The project your key belongs to (the project id is your organization id), for the Langfuse SDK's auth check. |
| GET /api/public/health | {"status": "OK"}. No key needed. |
Send the key as Authorization: Bearer xpl_..., as x-api-key: xpl_..., or as Authorization: Basic base64(public:secret), the Langfuse form, where the secret is your xpl_ key and the public key can be anything. Spans always go to the key's own organization. gRPC is not supported. Use OTLP over HTTP. The base URL is https://api-pr-902980.preview.experientiallabs.ai.
What we store
- Span names, ids, parents, times, status, model and token counts are always stored.
- Inputs, outputs, prompts, tool arguments and tool results are stored only while your organization stores prompt content and zero data retention is off. When storage is off we remove them as the span arrives. You still see the shape and timing of the trace.
- A cost you report on your own span is kept as
customer.cost_usd. It is never added to session or trace totals, because our span of the same call carries the exact charged cost.
Which attributes we read
| Fact | Attributes (the first one found wins) |
|---|---|
| Session | session.id, langfuse.session.id, gen_ai.conversation.id, explabs.session.id |
| End user | user.id, langfuse.user.id, enduser.id |
| Model | gen_ai.response.model, gen_ai.request.model, langfuse.observation.model.name, llm.model_name, ai.model.id, model |
| Tokens | gen_ai.usage.input_tokens and output_tokens, llm.token_count.*, ai.usage.*, input_tokens and output_tokens, langfuse.observation.usage_details |
| Tags | langfuse.trace.tags, tag.tags, explabs.tags (lists of key:value or names), explabs.tag.<key> |
| Step path | explabs.step_path |
A span with no session is filed under its trace. If one span of a trace names the session, later spans of that trace join it, even in later batches.
Limits and errors
| Limit (per organization) | Value | When you pass it |
|---|---|---|
| Request body | 4 MiB as sent, 16 MiB after gzip | 413 |
| Spans in one request | 2,000 | The rest are rejected through OTLP partial success (a 413 per Langfuse event). |
| Requests | 50 a second, bursts of 100 | 429 with Retry-After |
| Spans | 2,000 a second, bursts of 10,000 | 429 with Retry-After |
| Requests in progress at once | 4 | 429 with Retry-After |
| Status | Meaning |
|---|---|
| 400 invalid_payload | The body is not an OTLP export or a Langfuse batch. |
| 401 unauthorized | The key is missing, unknown or revoked. A customer-plan key cannot send spans. |
| 413 payload_too_large | Over 4 MiB as sent or 16 MiB inflated. |
| 415 unsupported_media_type, unsupported_encoding | Not protobuf or JSON, or not identity, gzip or deflate. |
| 429 rate_limited | Over a limit. Wait the Retry-After seconds. |
| 503 ingest_unavailable | We could not store the spans. Retry after Retry-After. |
Framework recipes
Replace xpl_... with your key. Every OTLP exporter reads these standard variables, and the recipes below use them:
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.experientiallabs.ai"export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer xpl_..."
To put our model span inside your own span, send the W3C traceparent header on the model call. OpenTelemetry's HTTP instrumentation does this for you.
Vercel AI SDK
import { registerOTel } from "@vercel/otel";export function register() {registerOTel({ serviceName: "my-agent" });}
const result = await generateText({model,prompt,experimental_telemetry: { isEnabled: true, functionId: "support-agent" },});
Mastra
Use the custom provider and turn logs off. We take traces only. Install @opentelemetry/exporter-trace-otlp-proto.
import { Mastra } from "@mastra/core";import { Observability } from "@mastra/observability";import { OtelExporter } from "@mastra/otel-exporter";export const mastra = new Mastra({observability: new Observability({configs: {otel: {serviceName: "my-agent",exporters: [new OtelExporter({provider: {custom: {endpoint: "https://api.experientiallabs.ai/v1/traces",protocol: "http/protobuf",headers: { "x-api-key": process.env.EXPLABS_API_KEY! },},},signals: { traces: true, logs: false },}),],},},}),});
LangGraph and LangChain
Either keep the Langfuse callback handler and change its host (below), or use OpenInference. Put the session on the spans with session.id.
from openinference.instrumentation.langchain import LangChainInstrumentorfrom opentelemetry import tracefrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporterfrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessorprovider = TracerProvider()provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))trace.set_tracer_provider(provider)LangChainInstrumentor().instrument(tracer_provider=provider)
OpenAI Agents SDK
Add an OpenTelemetry processor through OpenInference, with the variables above and the same tracer provider.
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentorOpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
Claude Agent SDK and Claude Code
Claude Code exports spans when tracing is on. Tracing is a beta and off by default. CLAUDE_CODE_PROPAGATE_TRACEPARENT makes each of our model spans nest under Claude Code's own span. Prompts and tool details stay out of its spans unless you also set OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 and OTEL_LOG_TOOL_CONTENT=1.
export CLAUDE_CODE_ENABLE_TELEMETRY=1export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1export OTEL_TRACES_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.experientiallabs.ai/v1/traces"export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer xpl_..."export CLAUDE_CODE_PROPAGATE_TRACEPARENT=1
Plain OpenTelemetry
Set the variables above and use any OTLP over HTTP exporter. Send session.id on your root span (or every span) to group runs into sessions.
Langfuse SDKs
Keep your Langfuse code and change two settings. LANGFUSE_PUBLIC_KEY can stay as it is. The host variable is LANGFUSE_HOST, LANGFUSE_BASE_URL or LANGFUSE_BASEURL, depending on the SDK version. Langfuse score-create events become scores on the span or trace they name.
export LANGFUSE_HOST="https://api.experientiallabs.ai"export LANGFUSE_SECRET_KEY="xpl_..."