--- title: Usa OpenTelemetry con la Claude API url: https://platform.claude.com/docs/it/manage-claude/opentelemetry/api description: Aggiungi una destinazione nella Claude Console per inviare le tracce OpenTelemetry delle tue richieste alla Messages API e delle sessioni di Managed Agents alla tua piattaforma di osservabilità. 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). Solo per le funzionalità a loro volta idonee per ZDR, come la Messages API. Claude Managed Agents non è idoneo per ZDR. supportedPlatforms: Claude API: beta Claude Platform on AWS: beta rows: - label: Compatibile con value: Messages API, Claude Managed Agents details: - Dopo la consegna, i dati sono conservati dal servizio che hai scelto, al di fuori di Anthropic, secondo i controlli di conservazione e di accesso di tale servizio. --- Con OpenTelemetry, la Claude API può emettere uno *span* (intervallo) per ogni richiesta al modello e per ogni uso di uno strumento che esegue. Puoi visualizzare questi span nella tua piattaforma di osservabilità senza modificare il tuo codice. L'API emette span per le tue richieste alla Messages API e per le sessioni di Managed Agents. Per riceverli, aggiungi una *destinazione* nella Claude Console. Una destinazione indica all'API l'endpoint OTLP della tua piattaforma di osservabilità e come autenticarsi con esso. ## Cosa ti serve * **Il ruolo di amministratore** in un'organizzazione della Claude Console, per aggiungere e modificare le destinazioni. Con il ruolo di sviluppatore puoi visualizzarle. Se la tua organizzazione è su Claude Platform on AWS, accedi alla Console tramite la AWS Console, come descritto in [Accesso](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#signing-in). * **Un endpoint OTLP/HTTP** che accetti la codifica protobuf su un URL HTTPS sulla porta 443. Se esegui un tuo [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), il suo receiver OTLP/HTTP è in ascolto sulla porta 4318 per impostazione predefinita. Configura il receiver per accettare HTTPS sulla porta 443, oppure metti un load balancer o un reverse proxy davanti al Collector. * **Credenziali per l'endpoint**, come una chiave API. ## 1. Aggiungi una destinazione Quando aggiungi una destinazione di telemetria, Anthropic invierà le trace dell'attività della Claude Platform nella tua organizzazione all'endpoint OTLP/HTTP del fornitore terzo che specifichi, in conformità con i termini del tuo fornitore e i controlli di accesso. Dopo la consegna, i dati sono conservati dal servizio che hai scelto, al di fuori di Anthropic, secondo i controlli di conservazione e di accesso di tale servizio. 1. Nella Console, apri la [pagina delle impostazioni OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) della tua organizzazione e fai clic su **Add destination**. 2. Configura la destinazione: | Campo | Cosa inserire | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Provider** | La tua piattaforma di osservabilità, oppure **Custom** se non è elencata. Se scegli una piattaforma elencata, la Console richiede i suoi dettagli, come una chiave API, al posto di **OTLP endpoint URL**, **Request headers** e **OTLP traces endpoint URL**. | | **Name** | Facoltativo. Ad esempio, "Piattaforma di osservabilità di Acme." | | **OTLP endpoint URL** | L'URL HTTPS di base dell'endpoint OTLP/HTTP della tua piattaforma di osservabilità, con un nome host, non un indirizzo IP. Può avere un prefisso di percorso, ad esempio `https://gateway.example.com/otlp`. Non aggiungere `/v1/traces`, perché l'API lo aggiunge. Se imposti un **OTLP traces endpoint URL**, l'API usa invece quell'URL. | | **Request headers** | Gli header che l'API invia con ogni richiesta, ad esempio l'header con la chiave API della tua piattaforma di osservabilità. Inserisci le credenziali solo nei valori degli header. Dopo il salvataggio, la Console non mostra più i valori. | | **Content mode** | **Metadata only** o **Full content**. Consulta [in cosa differiscono le modalità di contenuto](https://platform.claude.com/docs/it/manage-claude/opentelemetry#choose-a-content-mode). | | **Workspaces** | I workspace di cui la destinazione riceve gli span: **All**, **Selected** o **All except**. Consulta [Scegli i workspace per una destinazione](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#choose-workspaces-for-a-destination). | | **OTLP traces endpoint URL** | Facoltativo, in **Advanced settings**. L'URL completo dell'endpoint delle trace della tua piattaforma di osservabilità, ad esempio `https://gateway.example.com/custom/traces`. Impostalo quando la piattaforma riceve le trace a un URL diverso dall'OTLP endpoint URL più `/v1/traces`. Deve avere lo stesso host dell'OTLP endpoint URL. | | **Maximum content size in MB** | Facoltativo, in **Advanced settings** quando la modalità di contenuto è **Full content**. La quantità massima di contenuto che l'API invia in ogni span. La Console lo compila in base al **Provider** scelto. Modificalo in base a ciò che accetta la tua piattaforma di osservabilità. Lascialo vuoto per inviare la quantità massima consentita dall'API. Consulta [Limiti del contenuto](https://platform.claude.com/docs/it/manage-claude/opentelemetry#content-limits). | 3. Fai clic su **Add destination** per salvare. 4. Fai clic su **Test** nel menu **More actions** della destinazione. Vedrai un messaggio che indica che lo span di test è stato consegnato al tuo collector oppure in che modo la consegna non è riuscita (vedi [Errori di consegna](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#delivery-errors)). 5. Verifica che lo span `anthropic.test` sia arrivato nella tua piattaforma di osservabilità. ### Admin API e CLI Puoi anche aggiungere una destinazione tramite l'[Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api) invece che dalla Console. Accedi alla CLI come amministratore, oppure usa una [chiave Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api-keys) in `ANTHROPIC_API_KEY`. Su Claude Platform on AWS, invia invece le richieste a `https://aws-external-anthropic.{region}.api.aws`, firmate con le tue credenziali AWS come in [Effettuare richieste](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#making-requests). In tal caso, la tua [policy IAM](https://platform.claude.com/docs/it/api/claude-platform-on-aws-iam-actions) decide chi può gestire le destinazioni. Una richiesta può includere solo i workspace del tuo account AWS in quella Region. ```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 ``` Una richiesta di creazione accetta le impostazioni della Console tranne **Provider**, quindi inserisci tu stesso l'URL dell'endpoint e gli header della tua piattaforma di osservabilità. Imposta `traces.max_content_bytes` (csharp, go: `Traces.MaxContentBytes`; java, php: `traces.maxContentBytes`), in byte, in base a ciò che la tua piattaforma di osservabilità accetta (vedi [Limiti di contenuto](https://platform.claude.com/docs/it/manage-claude/opentelemetry#content-limits)). Per elencare, modificare o eliminare le destinazioni, oppure per aggiungere o rimuovere un workspace, usa gli altri metodi dell'API delle destinazioni di telemetria. ## 2. Scegli i workspace per una destinazione Una destinazione riceve gli span dei workspace che copre. Sceglili quando aggiungi la destinazione. Per **Workspaces**, seleziona una delle seguenti opzioni: * **All:** Ogni workspace dell'organizzazione, incluso il [Default Workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#how-workspaces-work) e i workspace creati in seguito. * **Selected:** Solo i workspace che selezioni. * **All except:** Come **All**, ma senza i workspace che selezioni. Per **Selected** o **All except**, seleziona i workspace nella casella di ricerca che appare sotto le opzioni. Per modificare in seguito i workspace di una destinazione, apri il suo menu **More actions** nella [pagina delle impostazioni di OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) mentre il filtro **Workspace** mostra **All**. Fai clic su **Edit**, quindi scegli un'altra opzione di **Workspaces** o modifica i workspace nella casella di ricerca. Se hai il ruolo di sviluppatore nell'organizzazione e il ruolo Workspace Admin in un workspace, puoi aggiungere quel workspace a una destinazione **Selected** o rimuoverlo da essa. Imposta il filtro **Workspace** su quel workspace, quindi apri il menu **More actions** della destinazione. Su Claude Platform on AWS, la Console non ha il ruolo Workspace Admin. Lì, è la tua [policy IAM](https://platform.claude.com/docs/it/api/claude-platform-on-aws-iam-actions) a decidere chi può aggiungere un workspace a una destinazione o rimuoverlo da essa. L'API invia gli span a ogni destinazione abilitata che copre il [workspace in cui viene eseguita la richiesta o la sessione](https://platform.claude.com/docs/it/manage-claude/workspaces#api-keys-and-resource-scoping). ## 3. Verifica che gli span arrivino 1. Nella Console, seleziona un workspace coperto dalla destinazione e invia una richiesta alla Messages API nel [playground](https://platform.claude.com/playground). Puoi anche inviare una richiesta alla Messages API dalla tua applicazione o avviare una sessione di Managed Agents in quel workspace. Per avviare una sessione, puoi seguire i passaggi in [Inizia con Claude Managed Agents](https://platform.claude.com/docs/it/managed-agents/quickstart). 2. Nella Console, nella [pagina delle impostazioni OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations), verifica che la colonna **Delivery** della destinazione mostri **Healthy**. Può richiedere circa un minuto. 3. Nella tua piattaforma di osservabilità, filtra per `service.name` = `claude-platform` per trovare gli span della richiesta. Se la colonna mostra **Failing**, passa il puntatore sopra di essa per vedere l'ultimo errore. Per trovare la causa probabile, consulta [Errori di consegna](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#delivery-errors). ## 4. Collega gli span dell'API alle tue tracce Per impostazione predefinita, gli span dell'API di una richiesta alla Messages API o di una sessione di Managed Agents si trovano in tracce separate. Collegali alle tracce della tua applicazione, in modo che siano annidati sotto i tuoi span. L'API legge il contesto di traccia di ogni richiesta dall'[header `traceparent`](https://www.w3.org/TR/trace-context/) W3C. Se il flag sampled nell'header è disattivato, l'API non emette lo span della richiesta né gli span sottostanti. Claude Platform on AWS non supporta ancora questo header. Gli span per le richieste che gli invii avviano sempre tracce separate, anche quando il flag sampled è disattivato. Per collegare gli span dell'API, [configura il tracciamento dell'SDK](https://platform.claude.com/docs/it/manage-claude/opentelemetry/sdk) nella tua applicazione e chiama l'SDK dall'interno di uno dei tuoi span. Il tuo span conterrà quindi lo span dell'SDK, che a sua volta contiene lo span dell'API. Invia tutti questi span alla stessa piattaforma di osservabilità, in modo che possa mostrarli come un'unica traccia. Consulta le tracce di esempio di [una richiesta alla Messages API](https://platform.claude.com/docs/it/manage-claude/opentelemetry#a-messages-api-request) e di [una sessione di Managed Agents](https://platform.claude.com/docs/it/manage-claude/opentelemetry#a-managed-agents-session). L'esempio seguente invia un messaggio utente a una sessione all'interno di un tuo 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; // Aggiungi questa sorgente al tuo tracer provider, accanto a com.anthropic.sdk.csharp. var source = new ActivitySource("MyService"); using (source.StartActivity("summarize_issues")) { // parameters contiene un evento user.message. await client.Beta.Sessions.Events.Send(session.ID, parameters); } ``` ```go Go // Passa il contesto che contiene il tuo span. ctx, span := otel.Tracer("my-service").Start(ctx, "summarize_issues") defer span.End() // params contiene un 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 contiene un 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 ``` L'SDK scrive l'header `traceparent` con il propagator della tua applicazione, e il flag sampled al suo interno segue il tuo sampler. Se la tua applicazione usa un propagator diverso dal W3C trace context, come B3, aggiungi anche il propagator W3C trace context. Copia il contesto di traccia dello span corrente negli header della richiesta, ad esempio quando crei una sessione di Managed Agents o invii un messaggio utente: ```bash cURL # TRACEPARENT è il traceparent dello span attivo nel tuo servizio, # ad esempio 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 il contesto di traccia dello span attivo negli header della richiesta. 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 il contesto di traccia dello span attivo negli header della richiesta. 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 imposta l'header 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 il contesto di traccia dello span attivo negli header della richiesta. 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 il contesto di traccia dello span attivo negli header della richiesta. 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 il contesto di traccia dello span attivo negli header della richiesta. 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 il trace context dello span attivo negli header della richiesta. 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 il contesto di traccia dello span attivo negli header della richiesta. 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 ) ``` La Messages API passa inoltre la traccia al tuo server MCP quando lo colleghi con il [connettore MCP](https://platform.claude.com/docs/it/agents-and-tools/mcp-connector), in modo che possa inserire i propri span sotto gli span dell'API. Ogni richiesta e notifica che l'API invia al tuo server MCP ha un `traceparent` W3C in `params._meta`. In una richiesta `tools/call`, fa riferimento allo span [`anthropic.mcp_tool_use`](https://platform.claude.com/docs/it/api/opentelemetry/spans#anthropic-tool-use-anthropic-mcp-tool-use-and-anthropic-custom-tool-use) di quell'uso degli strumenti. Negli altri messaggi, fa riferimento allo span [`anthropic.messages.create`](https://platform.claude.com/docs/it/api/opentelemetry/spans#anthropic-messages-create). Per una richiesta che l'API non traccia, come una il cui header `traceparent` ha il flag sampled disattivato, l'API non invia alcun `traceparent`. ## Passaggi successivi Ottieni osservabilità sul tuo client. Segui una richiesta dal tuo client fino alla Claude API. ## Consegna e stato Le regole seguenti si applicano agli span che l'API invia alle tue destinazioni. * **Almeno una volta:** Una destinazione può ricevere lo stesso span più di una volta. Per rimuovere i duplicati, usa il trace ID e lo span ID. * **Best effort:** Uno span può andare perso prima della consegna. L'API non può inviare di nuovo uno span perso. * **Compressione:** L'API comprime con gzip la prima richiesta di ogni consegna e imposta l'header `Content-Encoding: gzip`. Se il tuo endpoint risponde a quella richiesta con una risposta `400` o `415`, l'API invia immediatamente di nuovo gli stessi span senza compressione. * **Tentativi:** L'API ritenta la consegna in seguito, per un numero limitato di volte, dopo un timeout, un errore di connessione, TLS o DNS, oppure una risposta `408`, `429` o `5xx`. Non ritenta in caso di altri errori. * **Timeout:** Per ogni richiesta, il tuo endpoint deve completare l'handshake TLS entro 5 secondi e inviare gli header di risposta entro 5 secondi. Ogni consegna va in timeout dopo 10 secondi in totale, incluso il nuovo invio senza compressione. * **User agent:** Ogni richiesta ha l'header `User-Agent: Claude-Platform`. La colonna **Delivery** mostra lo stato di ciascuna destinazione. Lo stato può avere un ritardo fino a un minuto. | Stato di consegna | Significato | | ----------------- | --------------------------------------------------------------------------------------------- | | **Healthy** | L'ultima consegna è riuscita. | | **Failing** | L'ultima consegna non è riuscita. Per vedere l'errore, passa il puntatore sopra **Failing**. | | **No data** | L'API non ha ancora tentato una consegna. | | **Disabled** | La destinazione non riceve span. Per vedere il motivo, passa il puntatore sopra **Disabled**. | L'API disabilita una destinazione quando: * L'endpoint invia un reindirizzamento `3xx`. * Il nome host dell'endpoint si risolve in un indirizzo IP non pubblico. * Tutte le consegne falliscono per 24 ore. L'API non invia span a una destinazione disabilitata. Per riprendere l'esportazione, correggi la causa. Poi, con il filtro **Workspace** nella [pagina delle impostazioni di OpenTelemetry](https://platform.claude.com/settings/telemetry-destinations) impostato su **All**, fai clic su **Enable** nel menu **More actions** della destinazione. L'esportazione riprende entro circa un minuto. Per modificare una destinazione, apri il suo menu **More actions** mentre il filtro **Workspace** mostra **All**. Poi fai clic su **Edit**, **Disable**, **Enable** o **Delete**. Se modifichi l'host dell'**OTLP endpoint URL**, inserisci di nuovo i valori degli header. Se la destinazione ha un **OTLP traces endpoint URL**, assegnagli lo stesso nuovo host oppure svuotalo. ## Limiti | Limite | Valore | | ----------------------------------------------------------------- | --------------- | | Destinazioni per ogni organizzazione, incluse quelle disabilitate | 10 | | Workspace che selezioni per una destinazione | 1.000 | | Header di richiesta per ogni destinazione | 20 | | Lunghezza del nome di un header | 128 byte | | Lunghezza del valore di un header | 4.096 byte | | Lunghezza complessiva di tutti i nomi e valori degli header | 16.384 byte | | Lunghezza di un URL dell'endpoint | 2.048 caratteri | ## Risoluzione dei problemi | Problema | Cosa verificare | | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Nessuno span dell'API | Il workspace necessita di una destinazione abilitata che lo copra. Consulta [Scegli i workspace per una destinazione](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#choose-workspaces-for-a-destination). Dopo che una destinazione inizia a coprire un workspace, gli span di quel workspace possono impiegare fino a un minuto per arrivare. | | La colonna **Delivery** mostra **Failing** | Passa il puntatore sopra di essa per vedere l'ultimo errore. Per trovare la causa probabile, consulta [Errori di consegna](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#delivery-errors). | | La colonna **Delivery** mostra **Disabled** | Passa il puntatore sopra di essa per vedere il motivo. Per i motivi, consulta [quando l'API disabilita una destinazione](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#delivery-and-health). | | Gli span non contengono prompt o risposte, ma la destinazione è impostata su **Full content** | La tua organizzazione potrebbe avere una restrizione sulla gestione dei dati HIPAA, FERPA o K-12 con Anthropic. Consulta [Modalità di contenuto](https://platform.claude.com/docs/it/manage-claude/opentelemetry#choose-a-content-mode). | ### Errori di consegna Quando una consegna non riesce, la colonna **Delivery** mostra **Failing**. Passa il puntatore sopra per vedere l'errore, quindi individua la causa probabile: | Errore | Causa probabile | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP error (status 401) o HTTP error (status 403) | Un header di autenticazione errato | | HTTP error (status 404) | Un percorso errato nell'**OTLP endpoint URL** o nell'**OTLP traces endpoint URL** | | DNS resolution failure | Il nome host dell'endpoint non viene risolto | | TLS failure | Un problema TLS, ad esempio con il certificato dell'endpoint | | Timeout | L'endpoint non ha risposto in tempo. Consulta [i timeout di consegna](https://platform.claude.com/docs/it/manage-claude/opentelemetry/api#delivery-and-health) | | Connection failure | L'API non è riuscita a connettersi all'endpoint |