---
title: Use o OpenTelemetry com a Claude API
url: https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api
description: Adicione um destino no Claude Console para enviar traces do OpenTelemetry das suas requisições à Messages API e sessões do Managed Agents para a sua plataforma de observabilidade.
featureMetadata:
topic:
title: OpenTelemetry
url: https://platform.claude.com/docs/en/manage-claude/opentelemetry
status: beta
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Apenas para recursos que sejam elegíveis para ZDR por si só, como a Messages API. Claude Managed Agents não é elegível para ZDR.
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
rows:
- label: Compatível com
value: Messages API, Claude Managed Agents
details:
- Após a entrega, os dados ficam sob a guarda do serviço que você escolheu, fora da Anthropic, sujeitos aos controles de retenção e de acesso desse serviço.
---
Com o OpenTelemetry, a Claude API pode emitir um *span* (intervalo) para cada requisição ao modelo e para cada uso de ferramenta que ela executa. Você pode visualizar esses spans na sua plataforma de observabilidade sem alterar o seu código.
A API emite spans para as suas requisições à Messages API e para as sessões do Managed Agents. Para recebê-los, adicione um *destination* (destino) no Claude Console. Um destino informa à API o endpoint OTLP da sua plataforma de observabilidade e como se autenticar nele.
## O que você precisa
* **A função de administrador** em uma organização do Claude Console, para adicionar e alterar destinos. Com a função de desenvolvedor, você pode visualizá-los. Se a sua organização estiver no Claude Platform on AWS, faça login no Console pelo AWS Console, conforme descrito em [Fazendo login](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#signing-in).
* **Um endpoint OTLP/HTTP** que aceite codificação protobuf em uma URL HTTPS na porta 443. Se você executa seu próprio [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), o receptor OTLP/HTTP dele escuta na porta 4318 por padrão. Configure o receptor para aceitar HTTPS na porta 443 ou coloque um balanceador de carga ou proxy reverso na frente do Collector.
* **Credenciais para o endpoint**, como uma chave de API.
## 1. Adicione um destino
Quando você adiciona um destino de telemetria, a Anthropic enviará traces da atividade da Claude Platform na sua organização para o endpoint OTLP/HTTP do provedor terceirizado que você especificar, de acordo com os termos do seu provedor e os controles de acesso. Após a entrega, os dados ficam sob a guarda do serviço que você escolheu, fora da Anthropic, sujeitos aos controles de retenção e de acesso desse serviço.
1. No Console, abra a [página de configurações do OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) da sua organização e clique em **Add destination**.
2. Configure o destino:
| Campo | O que inserir |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider** | A sua plataforma de observabilidade, ou **Custom** se ela não estiver listada. Se escolher uma plataforma listada, o Console solicita os detalhes dela, como uma chave de API, em vez de **OTLP endpoint URL**, **Request headers** e **OTLP traces endpoint URL**. |
| **Name** | Opcional. Por exemplo, "Plataforma de observabilidade da Acme." |
| **OTLP endpoint URL** | A URL HTTPS base do endpoint OTLP/HTTP da sua plataforma de observabilidade, com um nome de host, não um endereço IP. Ela pode ter um prefixo de caminho, por exemplo `https://gateway.example.com/otlp`. Não adicione `/v1/traces`, pois a API o adiciona. Se você definir uma **OTLP traces endpoint URL**, a API usará essa URL em vez disso. |
| **Request headers** | Os cabeçalhos que a API envia com cada requisição, por exemplo o cabeçalho de chave de API da sua plataforma de observabilidade. Coloque credenciais somente nos valores dos cabeçalhos. Depois que você salva, o Console não mostra os valores novamente. |
| **Content mode** | **Metadata only** ou **Full content**. Veja [como os modos de conteúdo diferem](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#choose-a-content-mode). |
| **Workspaces** | Os workspaces cujos spans o destino recebe: **All**, **Selected** ou **All except**. Consulte [Escolha os workspaces de um destino](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#choose-workspaces-for-a-destination). |
| **OTLP traces endpoint URL** | Opcional, em **Advanced settings**. A URL completa do endpoint de traces da sua plataforma de observabilidade, por exemplo `https://gateway.example.com/custom/traces`. Defina-a quando a plataforma receber traces em uma URL diferente da OTLP endpoint URL acrescida de `/v1/traces`. Ela deve ter o mesmo host que a OTLP endpoint URL. |
| **Maximum content size in MB** | Opcional, em **Advanced settings** quando o modo de conteúdo é **Full content**. A quantidade máxima de conteúdo que a API envia em cada span. O Console o preenche com base no **Provider** que você escolher. Altere-o para se adequar ao que a sua plataforma de observabilidade aceita. Deixe-o vazio para enviar o máximo que a API permite. Consulte [Limites de conteúdo](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#content-limits). |
3. Clique em **Add destination** para salvar.
4. Clique em **Test** no menu **More actions** do destino. Você verá uma mensagem informando que o span de teste foi entregue ao seu coletor ou como a entrega falhou (consulte [Erros de entrega](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#delivery-errors)).
5. Verifique se o span `anthropic.test` chegou à sua plataforma de observabilidade.
### Admin API e CLI
Você também pode adicionar um destino com a [Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api) em vez do Console. Faça login na CLI como administrador ou use uma [chave da Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys) em `ANTHROPIC_API_KEY`. No Claude Platform on AWS, envie as requisições para `https://aws-external-anthropic.{region}.api.aws` em vez disso, assinadas com as suas credenciais da AWS, como em [Fazendo requisições](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#making-requests). Nesse caso, a sua [política do IAM](https://platform.claude.com/docs/pt-BR/api/claude-platform-on-aws-iam-actions) decide quem pode gerenciar destinos. Uma requisição pode incluir somente os workspaces da sua conta da AWS nessa Região.
```bash CLI
# Sign in once as an admin, which opens a browser. Leave ANTHROPIC_API_KEY unset, because it overrides the profile.
ant auth login --profile admin --scope "org:admin"
ant --profile admin beta:organization:telemetry-destinations create \
--endpoint-url https://gateway.example.com/otlp \
--headers '{authorization: "Bearer YOUR_OBSERVABILITY_API_KEY"}' \
--traces.content-mode metadata_only \
--workspaces.type all
```
```bash cURL
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://gateway.example.com/otlp",
"headers": {"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
"traces": {"content_mode": "metadata_only"},
"workspaces": {"type": "all"}
}'
```
```python Python
client = anthropic.Anthropic()
destination = client.beta.organization.telemetry_destinations.create(
endpoint_url="https://gateway.example.com/otlp",
headers={"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY"},
traces={"content_mode": "metadata_only"},
workspaces={"type": "all"},
)
print(destination.id)
```
```typescript TypeScript
const client = new Anthropic();
const destination = await client.beta.organization.telemetryDestinations.create({
endpoint_url: "https://gateway.example.com/otlp",
headers: { authorization: "Bearer YOUR_OBSERVABILITY_API_KEY" },
traces: { content_mode: "metadata_only" },
workspaces: { type: "all" }
});
console.log(destination.id);
```
```csharp C#
using Anthropic.Models.Beta.Organization.TelemetryDestinations;
AnthropicClient client = new();
var destination = await client.Beta.Organization.TelemetryDestinations.Create(
new()
{
EndpointUrl = "https://gateway.example.com/otlp",
Headers = new Dictionary
{
["authorization"] = "Bearer YOUR_OBSERVABILITY_API_KEY",
},
Traces = new() { ContentMode = BetaTelemetryDestinationContentMode.MetadataOnly },
Workspaces = new BetaTelemetryDestinationWorkspacesAllParams(),
}
);
Console.WriteLine(destination.ID);
```
```go Go
client := anthropic.NewClient()
destination, err := client.Beta.Organization.TelemetryDestinations.New(
context.Background(),
anthropic.BetaOrganizationTelemetryDestinationNewParams{
EndpointURL: "https://gateway.example.com/otlp",
Headers: map[string]string{
"authorization": "Bearer YOUR_OBSERVABILITY_API_KEY",
},
Traces: anthropic.BetaTelemetryDestinationTracesParams{
ContentMode: anthropic.BetaTelemetryDestinationContentModeMetadataOnly,
},
Workspaces: anthropic.BetaTelemetryDestinationWorkspacesParamsUnion{
OfAll: &anthropic.BetaTelemetryDestinationWorkspacesAllParams{},
},
},
)
if err != nil {
log.Fatal(err)
}
fmt.Println(destination.ID)
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationContentMode;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationTracesParams;
import com.anthropic.models.beta.organization.telemetrydestinations.BetaTelemetryDestinationWorkspacesAllParams;
import com.anthropic.models.beta.organization.telemetrydestinations.TelemetryDestinationCreateParams;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
var params = TelemetryDestinationCreateParams.builder()
.endpointUrl("https://gateway.example.com/otlp")
.headers(TelemetryDestinationCreateParams.Headers.builder()
.putAdditionalProperty("authorization", JsonValue.from("Bearer YOUR_OBSERVABILITY_API_KEY"))
.build())
.traces(BetaTelemetryDestinationTracesParams.builder()
.contentMode(BetaTelemetryDestinationContentMode.METADATA_ONLY)
.build())
.workspaces(BetaTelemetryDestinationWorkspacesAllParams.builder().build())
.build();
var destination = client.beta().organization().telemetryDestinations().create(params);
IO.println(destination.id());
}
```
```php PHP
$client = new Client();
$destination = $client->beta->organization->telemetryDestinations->create(
endpointURL: 'https://gateway.example.com/otlp',
headers: ['authorization' => 'Bearer YOUR_OBSERVABILITY_API_KEY'],
traces: ['contentMode' => 'metadata_only'],
workspaces: ['type' => 'all'],
);
echo "{$destination->id}\n";
```
```ruby Ruby
client = Anthropic::Client.new
destination = client.beta.organization.telemetry_destinations.create(
endpoint_url: "https://gateway.example.com/otlp",
headers: {authorization: "Bearer YOUR_OBSERVABILITY_API_KEY"},
traces: {content_mode: :metadata_only},
workspaces: {type: :all}
)
puts destination.id
```
Uma solicitação de criação aceita as configurações do Console, exceto **Provider**, então insira você mesmo a URL do endpoint e os cabeçalhos da sua plataforma de observabilidade. Defina `traces.max_content_bytes` (csharp, go: `Traces.MaxContentBytes`; java, php: `traces.maxContentBytes`), em bytes, para se adequar ao que a sua plataforma de observabilidade aceita (veja [Limites de conteúdo](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#content-limits)). Para listar, alterar ou excluir destinos, ou para adicionar ou remover um workspace, use os outros métodos da API de destinos de telemetria.
## 2. Escolha os workspaces de um destino
Um destino recebe os spans dos workspaces que ele abrange. Escolha-os ao adicionar o destino. Em **Workspaces**, selecione uma das seguintes opções:
* **All:** Todos os workspaces da organização, incluindo o [Default Workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#how-workspaces-work) e os workspaces criados posteriormente.
* **Selected:** Somente os workspaces que você selecionar.
* **All except:** Como **All**, mas sem os workspaces que você selecionar.
Para **Selected** ou **All except**, selecione os workspaces na caixa de pesquisa que aparece abaixo das opções. Para alterar os workspaces de um destino posteriormente, abra o menu **More actions** dele na [página de configurações do OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) enquanto o filtro **Workspace** mostra **All**. Clique em **Edit** e, em seguida, escolha outra opção de **Workspaces** ou altere os workspaces na caixa de pesquisa.
Se você tiver a função de desenvolvedor na organização e a função Workspace Admin em um workspace, poderá adicionar esse workspace a um destino **Selected** ou removê-lo desse destino. Defina o filtro **Workspace** para esse workspace e, em seguida, abra o menu **More actions** do destino. No Claude Platform on AWS, o Console não tem a função Workspace Admin. Nele, é a sua [política do IAM](https://platform.claude.com/docs/pt-BR/api/claude-platform-on-aws-iam-actions) que determina quem pode adicionar um workspace a um destino ou removê-lo dele.
A API envia spans para todos os destinos habilitados que cobrem o [workspace em que a requisição ou sessão é executada](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#api-keys-and-resource-scoping).
## 3. Verifique se os spans chegam
1. No Console, selecione um workspace coberto pelo destino e envie uma requisição à Messages API no [playground](https://platform.claude.com/playground). Você também pode enviar uma requisição à Messages API a partir da sua aplicação ou iniciar uma sessão do Managed Agents nesse workspace. Para iniciar uma sessão, você pode seguir as etapas em [Primeiros passos com o Claude Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/quickstart).
2. No Console, na [página de configurações do OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations), verifique se a coluna **Delivery** do destino mostra **Healthy**. Isso pode levar cerca de um minuto.
3. Na sua plataforma de observabilidade, filtre por `service.name` = `claude-platform` para encontrar os spans da requisição.
Se a coluna mostrar **Failing**, passe o ponteiro sobre ela para ver o último erro. Para encontrar a causa provável, consulte [Erros de entrega](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#delivery-errors).
## 4. Conecte os spans da API aos seus próprios traces
Por padrão, os spans da API de uma requisição à Messages API ou de uma sessão do Managed Agents ficam em traces próprios. Conecte-os aos traces da sua aplicação para que fiquem aninhados sob os seus próprios spans.
A API lê o contexto de trace de cada requisição a partir do [cabeçalho `traceparent`](https://www.w3.org/TR/trace-context/) do W3C. Se a flag de amostragem no cabeçalho estiver desativada, a API não emite o span da requisição nem os spans abaixo dele. O Claude Platform on AWS ainda não oferece suporte a esse cabeçalho. Os spans das requisições que você envia a ele sempre iniciam traces próprios, mesmo quando a flag de amostragem está desativada.
Para conectar os spans da API, [configure o tracing do SDK](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/sdk) na sua aplicação e chame o SDK de dentro de um dos seus próprios spans. Seu span passa então a conter o span do SDK, que contém o span da API. Envie todos esses spans para a mesma plataforma de observabilidade, para que ela possa exibi-los como um único trace. Veja os traces de exemplo de [uma requisição à Messages API](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#a-messages-api-request) e de [uma sessão do Managed Agents](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#a-managed-agents-session).
O exemplo a seguir envia uma mensagem de usuário para uma sessão dentro do seu próprio span:
```python Python
from opentelemetry import trace
tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("summarize_issues"):
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}],
},
],
)
```
```typescript TypeScript
import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-service");
await tracer.startActiveSpan("summarize_issues", async (span) => {
try {
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.message",
content: [{ type: "text", text: "Summarize the open issues" }]
}
]
});
} finally {
span.end();
}
});
```
```csharp C#
using System.Diagnostics;
// Adicione esta fonte ao seu tracer provider, junto com com.anthropic.sdk.csharp.
var source = new ActivitySource("MyService");
using (source.StartActivity("summarize_issues"))
{
// parameters contém um evento user.message.
await client.Beta.Sessions.Events.Send(session.ID, parameters);
}
```
```go Go
// Passe o contexto que contém o seu span.
ctx, span := otel.Tracer("my-service").Start(ctx, "summarize_issues")
defer span.End()
// params contém um evento user.message.
_, err := client.Beta.Sessions.Events.Send(ctx, session.ID, params)
```
```java Java
Tracer tracer = GlobalOpenTelemetry.getTracer("my-service");
Span span = tracer.spanBuilder("summarize_issues").startSpan();
try (Scope scope = span.makeCurrent()) {
// params contém um evento user.message.
client.beta().sessions().events().send(session.id(), params);
} finally {
span.end();
}
```
```php PHP
use OpenTelemetry\API\Globals;
$tracer = Globals::tracerProvider()->getTracer('my-service');
$span = $tracer->spanBuilder('summarize_issues')->startSpan();
$scope = $span->activate();
try {
$client->beta->sessions->events->send(
$session->id,
events: [
[
'type' => 'user.message',
'content' => [
['type' => 'text', 'text' => 'Summarize the open issues'],
],
],
],
);
} finally {
$scope->detach();
$span->end();
}
```
```ruby Ruby
tracer = OpenTelemetry.tracer_provider.tracer("my-service")
tracer.in_span("summarize_issues") do
client.beta.sessions.events.send_(
session.id,
events: [
{
type: "user.message",
content: [{type: "text", text: "Summarize the open issues"}]
}
]
)
end
```
O SDK grava o cabeçalho `traceparent` com o propagador da sua aplicação, e a flag de amostragem nele segue o seu sampler. Se a sua aplicação usa um propagador diferente do W3C trace context, como o B3, adicione também o propagador W3C trace context.
Copie o contexto de trace do span atual para os cabeçalhos da requisição, por exemplo ao criar uma sessão do Managed Agents ou enviar uma mensagem de usuário:
```bash cURL
# TRACEPARENT é o traceparent do span ativo no seu próprio serviço,
# por exemplo, 00---01.
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-H "traceparent: $TRACEPARENT" \
-d '{
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}]
}
]
}'
```
```python Python
import os
import httpx2
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
headers = {
"x-api-key": os.environ["ANTHROPIC_API_KEY"],
"anthropic-version": "2023-06-01",
"anthropic-beta": "managed-agents-2026-04-01",
"content-type": "application/json",
}
# Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
TraceContextTextMapPropagator().inject(headers)
httpx2.post(
f"https://api.anthropic.com/v1/sessions/{os.environ['SESSION_ID']}/events",
headers=headers,
json={
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}],
},
],
},
)
```
```typescript TypeScript
import { context, defaultTextMapSetter } from "@opentelemetry/api";
import { W3CTraceContextPropagator } from "@opentelemetry/core";
const headers: Record = {
"x-api-key": process.env.ANTHROPIC_API_KEY!,
"anthropic-version": "2023-06-01",
"anthropic-beta": "managed-agents-2026-04-01",
"content-type": "application/json"
};
// Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
new W3CTraceContextPropagator().inject(context.active(), headers, defaultTextMapSetter);
await fetch(`https://api.anthropic.com/v1/sessions/${process.env.SESSION_ID}/events`, {
method: "POST",
headers,
body: JSON.stringify({
events: [
{
type: "user.message",
content: [{ type: "text", text: "Summarize the open issues" }]
}
]
})
});
```
```csharp C#
using System.Diagnostics;
using System.Net.Http.Json;
using OpenTelemetry;
using OpenTelemetry.Context.Propagation;
using var httpClient = new HttpClient();
using var request = new HttpRequestMessage(
HttpMethod.Post,
$"https://api.anthropic.com/v1/sessions/{Environment.GetEnvironmentVariable("SESSION_ID")}/events")
{
// JsonContent define o cabeçalho content-type.
Content = JsonContent.Create(new
{
events = new[]
{
new
{
type = "user.message",
content = new[] { new { type = "text", text = "Summarize the open issues" } },
},
},
}),
};
request.Headers.Add("x-api-key", Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));
request.Headers.Add("anthropic-version", "2023-06-01");
request.Headers.Add("anthropic-beta", "managed-agents-2026-04-01");
// Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
new TraceContextPropagator().Inject(
new PropagationContext(Activity.Current?.Context ?? default, Baggage.Current),
request,
(carrier, key, value) => carrier.Headers.Add(key, value));
await httpClient.SendAsync(request);
```
```go Go
import (
"context"
"net/http"
"os"
"strings"
"go.opentelemetry.io/otel/propagation"
)
func sendMessage(ctx context.Context) error {
body := strings.NewReader(`{
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}]
}
]
}`)
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
"https://api.anthropic.com/v1/sessions/"+os.Getenv("SESSION_ID")+"/events", body)
if err != nil {
return err
}
req.Header.Set("x-api-key", os.Getenv("ANTHROPIC_API_KEY"))
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("anthropic-beta", "managed-agents-2026-04-01")
req.Header.Set("content-type", "application/json")
// Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
propagation.TraceContext{}.Inject(ctx, propagation.HeaderCarrier(req.Header))
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
return resp.Body.Close()
}
```
```java Java
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.Context;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
void main() throws Exception {
var request = HttpRequest.newBuilder(URI.create(
"https://api.anthropic.com/v1/sessions/" + System.getenv("SESSION_ID") + "/events"))
.header("x-api-key", System.getenv("ANTHROPIC_API_KEY"))
.header("anthropic-version", "2023-06-01")
.header("anthropic-beta", "managed-agents-2026-04-01")
.header("content-type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString("""
{
"events": [
{
"type": "user.message",
"content": [{"type": "text", "text": "Summarize the open issues"}]
}
]
}
"""));
// Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
W3CTraceContextPropagator.getInstance()
.inject(Context.current(), request, HttpRequest.Builder::header);
HttpClient.newHttpClient().send(request.build(), HttpResponse.BodyHandlers.ofString());
}
```
```php PHP
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
$headers = [
'x-api-key' => getenv('ANTHROPIC_API_KEY'),
'anthropic-version' => '2023-06-01',
'anthropic-beta' => 'managed-agents-2026-04-01',
'content-type' => 'application/json',
];
// Copia o contexto de rastreamento do span ativo para os cabeçalhos da requisição.
TraceContextPropagator::getInstance()->inject($headers);
$ch = curl_init('https://api.anthropic.com/v1/sessions/' . getenv('SESSION_ID') . '/events');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => array_map(
static fn ($name, $value) => "$name: $value",
array_keys($headers),
$headers,
),
CURLOPT_POSTFIELDS => json_encode([
'events' => [
[
'type' => 'user.message',
'content' => [
['type' => 'text', 'text' => 'Summarize the open issues'],
],
],
],
]),
]);
curl_exec($ch);
```
```ruby Ruby
require "json"
require "net/http"
require "opentelemetry"
headers = {
"x-api-key" => ENV.fetch("ANTHROPIC_API_KEY"),
"anthropic-version" => "2023-06-01",
"anthropic-beta" => "managed-agents-2026-04-01",
"content-type" => "application/json"
}
# Copia o contexto de trace do span ativo para os cabeçalhos da requisição.
OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator.inject(headers)
Net::HTTP.post(
URI("https://api.anthropic.com/v1/sessions/#{ENV.fetch("SESSION_ID")}/events"),
{
events: [
{
type: "user.message",
content: [{type: "text", text: "Summarize the open issues"}]
}
]
}.to_json,
headers
)
```
A Messages API também repassa o trace para o seu servidor MCP quando você o conecta com o [conector MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector), para que ele possa colocar os seus próprios spans sob os spans da API. Cada requisição e notificação que a API envia ao seu servidor MCP tem um `traceparent` do W3C em `params._meta`. Em uma requisição `tools/call`, ele referencia o span [`anthropic.mcp_tool_use`](https://platform.claude.com/docs/pt-BR/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) desse uso de ferramentas. Nas outras mensagens, ele referencia o span [`anthropic.messages.create`](https://platform.claude.com/docs/pt-BR/api/opentelemetry/spans#anthropic-messages-create). Para uma requisição que a API não rastreia, como uma cujo cabeçalho `traceparent` tem o sinalizador de amostragem desativado, a API não envia nenhum `traceparent`.
## Próximos passos
Obtenha observabilidade no seu cliente.
Acompanhe uma requisição desde o seu cliente até a Claude API.
## Entrega e integridade
As regras a seguir se aplicam aos spans que a API envia para os seus destinos.
* **Pelo menos uma vez:** Um destino pode receber o mesmo span mais de uma vez. Para remover duplicatas, use o ID do trace e o ID do span.
* **Melhor esforço:** Um span pode ser perdido antes da entrega. A API não consegue enviar novamente um span perdido.
* **Compressão:** A API comprime a primeira requisição de cada entrega com gzip e define o cabeçalho `Content-Encoding: gzip`. Se o seu endpoint responder a essa requisição com uma resposta `400` ou `415`, a API envia os mesmos spans novamente de imediato, sem compressão.
* **Novas tentativas:** A API tenta a entrega novamente mais tarde, um número limitado de vezes, após um timeout, uma falha de conexão, TLS ou DNS, ou uma resposta `408`, `429` ou `5xx`. Ela não tenta novamente em outras falhas.
* **Timeouts:** Para cada requisição, o seu endpoint deve concluir o handshake TLS em até 5 segundos e enviar os cabeçalhos de resposta em até 5 segundos. Cada entrega expira após 10 segundos no total, incluindo o reenvio sem compressão.
* **User agent:** Cada requisição tem o cabeçalho `User-Agent: Claude-Platform`.
A coluna **Delivery** mostra o estado de cada destino. O estado pode ter até um minuto de atraso.
| Estado de entrega | Significado |
| ----------------- | ----------------------------------------------------------------------------------- |
| **Healthy** | A última entrega foi bem-sucedida. |
| **Failing** | A última entrega falhou. Para ver o erro, passe o ponteiro sobre **Failing**. |
| **No data** | A API ainda não tentou nenhuma entrega. |
| **Disabled** | O destino não recebe spans. Para ver o motivo, passe o ponteiro sobre **Disabled**. |
A API desabilita um destino quando:
* O endpoint envia um redirecionamento `3xx`.
* O nome de host do endpoint é resolvido para um endereço IP que não é público.
* Todas as entregas falham por 24 horas.
A API não envia spans para um destino desativado. Para retomar a exportação, corrija a causa. Em seguida, com o filtro **Workspace** na [página de configurações do OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) mostrando **All**, clique em **Enable** no menu **More actions** do destino. A exportação recomeça em cerca de um minuto.
Para alterar um destino, abra seu menu **More actions** enquanto o filtro **Workspace** mostra **All**. Em seguida, clique em **Edit**, **Disable**, **Enable** ou **Delete**. Se você alterar o host da **OTLP endpoint URL**, insira os valores dos cabeçalhos novamente. Se o destino tiver uma **OTLP traces endpoint URL**, atribua a ela o mesmo novo host ou limpe-a.
## Limites
| Limite | Valor |
| ----------------------------------------------------------- | ---------------- |
| Destinos por organização, incluindo os desabilitados | 10 |
| Workspaces que você seleciona para um destino | 1.000 |
| Cabeçalhos de requisição por destino | 20 |
| Comprimento de um nome de cabeçalho | 128 bytes |
| Comprimento de um valor de cabeçalho | 4.096 bytes |
| Comprimento de todos os nomes e valores de cabeçalho juntos | 16.384 bytes |
| Comprimento de uma URL de endpoint | 2.048 caracteres |
## Solução de problemas
| Problema | O que verificar |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nenhum span da API | O workspace precisa de um destino habilitado que o cubra. Consulte [Escolha os workspaces de um destino](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#choose-workspaces-for-a-destination). Depois que um destino começa a cobrir um workspace, os spans desse workspace podem levar até um minuto para chegar. |
| A coluna **Delivery** mostra **Failing** | Passe o ponteiro sobre ela para ver o último erro. Para encontrar a causa provável, consulte [Erros de entrega](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#delivery-errors). |
| A coluna **Delivery** mostra **Disabled** | Passe o ponteiro sobre ela para ver o motivo. Para os motivos, consulte [quando a API desabilita um destino](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#delivery-and-health). |
| Os spans não têm prompts nem respostas, mas o destino está definido como **Full content** | Sua organização pode ter uma restrição de tratamento de dados HIPAA, FERPA ou K-12 com a Anthropic. Consulte [Modos de conteúdo](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry#choose-a-content-mode). |
### Erros de entrega
Quando uma entrega falha, a coluna **Delivery** mostra **Failing**. Passe o ponteiro sobre esse estado para ver o erro e, em seguida, identifique a causa provável:
| Erro | Causa provável |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP error (status 401) ou HTTP error (status 403) | Um cabeçalho de autenticação incorreto |
| HTTP error (status 404) | Um caminho incorreto na **OTLP endpoint URL** ou na **OTLP traces endpoint URL** |
| DNS resolution failure | O hostname do endpoint não é resolvido |
| TLS failure | Um problema de TLS, por exemplo com o certificado do endpoint |
| Timeout | O endpoint não respondeu a tempo. Consulte [os tempos limite de entrega](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/api#delivery-and-health) |
| Connection failure | A API não conseguiu se conectar ao endpoint |