Send Claude API Traces to KloudMate

The Claude API and the Claude SDK can emit an OpenTelemetry span for each Messages API request, model run, tool use, and Managed Agents turn. Send these spans to KloudMate to debug failed or slow requests, track token usage and latency, and see each Claude call inside your application’s own traces.

You can send traces from two places, and you can use both at once:

• API tracing sends spans from the Claude API itself. You add a destination in the Claude Console, and every request in the workspaces it covers is traced, from any client, with no code change. It’s the only way to see each model run inside a request, server tools such as web search, and Managed Agents turns.
• SDK tracing sends spans from the Claude SDK in your application, through your own OpenTelemetry exporter. It also traces the client tools that the SDK’s tool runner runs, and it nests each Claude call under your application’s spans.

To monitor Claude Code, Claude Desktop, or Cowork instead, see Send Claude Code and Cowork Telemetry to KloudMate.

Note

OpenTelemetry export for the Claude API is in beta. Span and attribute names can change between versions, so check the Claude OpenTelemetry docs if a query or dashboard stops matching.

Prerequisites

• A KloudMate workspace API key, from Settings → Ingest Keys.
• For API tracing, the admin role in your Claude Console organization. With the developer role, you can view destinations but not add them.
• For SDK tracing, the KloudMate agent on the machine that runs your application, or your API key to send to KloudMate directly.

Send API traces from the Claude Console

The Claude API sends spans over OTLP/HTTP to a public HTTPS endpoint on port 443, so the destination points at KloudMate directly, not at a local KloudMate agent.

1. In the Claude Console, open the OpenTelemetry settings page and click Add destination.

2. Fill in the destination:

Field	Value
Provider	Custom
Name	KloudMate
OTLP endpoint URL	https://otel.kloudmate.com. Don’t add /v1/traces, because the API adds it.
Request headers	Name Authorization, value your KloudMate API key, with no Bearer prefix.
Content mode	Metadata only or Full content. See Choose a content mode.
Workspaces	All, or the Claude workspaces you want to trace.

3. Click Add destination.

4. In the destination’s More actions menu, click Test. The Console sends an anthropic.test span and shows whether it was delivered.

5. Send a Messages API request from a workspace the destination covers, for example from the Console playground. Within about a minute, the destination’s Delivery column shows Healthy.

6. In KloudMate, go to Traces and filter by the service claude-platform. Every span from the Claude API has this service name.

You can also add the destination with the Admin API instead of the Console. Use an Admin API key in ANTHROPIC_API_KEY:

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/telemetry_destinations" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: telemetry-destinations-2026-08-11" \
  -H "content-type: application/json" \
  -d '{
    "endpoint_url": "https://otel.kloudmate.com",
    "headers": {"Authorization": "YOUR_KLOUDMATE_API_KEY"},
    "traces": {"content_mode": "metadata_only"},
    "workspaces": {"type": "all"}
  }'

Send SDK traces from your application

The Claude SDK emits its spans through the tracer provider that your application registers, so your Claude calls stay the same. Register the tracer provider before the first call you want to trace.

1. Install the Claude SDK and the OpenTelemetry SDK with an OTLP exporter:

Python

pip install --upgrade anthropic opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

TypeScript

npm install @anthropic-ai/sdk@latest @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

2. Set the service name and the endpoint. The exporter reads both from the environment:

export OTEL_SERVICE_NAME="my-claude-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export ANTHROPIC_API_KEY="YOUR_CLAUDE_API_KEY"

http://localhost:4318 is the KloudMate agent on the same machine, which forwards the spans to KloudMate with your workspace’s API key. To send to KloudMate directly instead, set the endpoint to https://otel.kloudmate.com:4318 and add your key:

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=YOUR_KLOUDMATE_API_KEY"

3. Register a tracer provider with the OTLP exporter, then call Claude as usual:

Python

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

TypeScript

import Anthropic from "@anthropic-ai/sdk";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const sdk = new NodeSDK({ traceExporter: new OTLPTraceExporter() });
sdk.start();

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});
console.log(message.content);

// Flush the spans before a short script exits.
await sdk.shutdown();

4. Run the application. In KloudMate, go to Traces and filter by the service my-claude-app. Each Claude call appears as an anthropic.messages.create span.

The C#, Go, Java, PHP, and Ruby SDKs work the same way. For their setup, see Set up OpenTelemetry with the Claude SDK.

Caution

If your Node.js application also uses @opentelemetry/auto-instrumentations-node, create the client with new Anthropic({ openTelemetry: { propagation: false } }). Otherwise, the undici instrumentation adds a second traceparent header to each request, and the trace context becomes invalid.

Connect Claude API spans to your traces

With both API tracing and SDK tracing on, call the SDK from inside one of your own spans. The SDK sends the trace context to the Claude API in the traceparent header, so the API spans nest under the SDK span, which nests under yours. In KloudMate, the request then reads as one trace, from your handler down to each model run and tool use.

tracer = trace.get_tracer("my-claude-app")

with tracer.start_as_current_span("answer_question"):
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    )

To group the calls of one conversation, pass a conversation ID to the SDK. It’s written to gen_ai.conversation.id on every span, so you can filter by it in KloudMate. The ID is exported in both content modes, so don’t put personal data or secrets in it.

Choose a content mode

The content mode sets whether spans include prompts and responses:

• Metadata only is the default. Spans carry IDs, timing, status, token counts, and the names of your agents, tools, and MCP servers.
• Full content adds the system prompt, the input messages, and the model’s response, in gen_ai.system_instructions, gen_ai.input.messages, and gen_ai.output.messages. Use it to read full conversations and see why a run failed or was slow.

For API tracing, set it on the destination. For SDK tracing, set ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content.

With Full content, prompts and responses are stored in KloudMate under your workspace’s retention settings, so check that this meets your organization’s requirements before you turn it on. Each span holds up to 0.75 MB of content by default, and longer content is shortened and marked with anthropic.content.truncated.

Read the spans

Span	Emitted by	What it covers
anthropic.messages.create	SDK (CLIENT) and API (SERVER)	One Messages API request
anthropic.model_request	API	One model run inside a request
anthropic.tool_use, anthropic.mcp_tool_use	API	A server tool or an MCP connector tool that the API runs
anthropic.custom_tool_use	SDK	A client tool that the SDK’s tool runner runs
anthropic.session.turn	API	One Managed Agents turn

Token usage is in gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, and gen_ai.usage.input_tokens already includes prompt cache reads and writes. A request’s usage appears on more than one span, so when you chart tokens, sum only the anthropic.messages.create spans from one source. If you use both API and SDK tracing, sum the SERVER spans.

For every span and attribute, see the Claude OpenTelemetry span reference. For what KloudMate shows on an LLM trace, see Agentic Workflow Observability.

Troubleshooting

Problem	What to check
The Delivery column shows Failing with status 401 or 403	The Authorization header doesn’t hold a valid KloudMate API key. Edit the destination and enter the key again, with no Bearer prefix.
The Delivery column shows Failing with status 404	The OTLP endpoint URL has a path. Set it to https://otel.kloudmate.com.
The Delivery column shows Disabled	The API disables a destination after 24 hours of failed deliveries. Fix the cause, then click Enable in the destination’s More actions menu.
No API spans in KloudMate	The destination must cover the Claude workspace that the request ran in. Spans can take a minute to arrive.
No SDK spans in KloudMate	Register the tracer provider before the first Claude call, and check that ANTHROPIC_OPEN_TELEMETRY isn’t set to false. For a short script, flush the spans before it exits.
Each request appears twice	The SDK span and the API span are both named anthropic.messages.create. Tell them apart by span kind or by service name.