OpenTelemetry mit der Claude API verwenden

Mit OpenTelemetry kann die Claude API für jede Modellanfrage und jede Tool-Nutzung, die sie ausführt, einen span (Span) ausgeben. Du kannst diese Spans in deiner Observability-Plattform ansehen, ohne deinen Code zu ändern.

Die API erzeugt Spans für deine Messages-API-Anfragen und Managed-Agents-Sessions. Um sie zu empfangen, füge in der Claude Console ein destination (Ziel) hinzu. Ein Ziel teilt der API den OTLP-Endpunkt deiner Observability-Plattform mit und wie sie sich dort authentifiziert.

Was du brauchst

• Die Admin-Rolle in einer Claude Console-Organisation, um Ziele hinzuzufügen und zu ändern. Mit der Entwickler-Rolle kannst du sie ansehen. Wenn deine Organisation Claude Platform on AWS nutzt, melde dich über die AWS Console bei der Console an, wie unter Anmelden beschrieben.
• Ein OTLP/HTTP-Endpunkt, der Protobuf-Kodierung unter einer HTTPS-URL auf Port 443 akzeptiert. Wenn du deinen eigenen OpenTelemetry Collector betreibst, lauscht dessen OTLP/HTTP-Receiver standardmäßig auf Port 4318. Konfiguriere den Receiver so, dass er HTTPS auf Port 443 akzeptiert, oder setze einen Load Balancer oder Reverse Proxy vor den Collector.
• Anmeldedaten für den Endpunkt, etwa einen API-Key.

1. Ein Ziel hinzufügen

1. Öffne in der Console die OpenTelemetry-Einstellungsseite deiner Organisation und klicke auf Add destination.

2. Konfiguriere das Ziel:

   Feld	Was du eingibst
   Provider	Deine Observability-Plattform oder Custom, wenn sie nicht aufgeführt ist. Wenn du eine aufgeführte Plattform auswählst, fragt die Console anstelle von OTLP endpoint URL, Request headers und OTLP traces endpoint URL nach deren Details, etwa einem API-Key.
   Name	Optional. Zum Beispiel „Acmes Observability-Plattform".
   OTLP endpoint URL	Die Basis-HTTPS-URL des OTLP/HTTP-Endpunkts deiner Observability-Plattform, mit einem Hostnamen, nicht einer IP-Adresse. Sie kann ein Pfadpräfix haben, zum Beispiel https://gateway.example.com/otlp. Füge nicht /v1/traces hinzu, da die API es hinzufügt. Wenn du eine OTLP traces endpoint URL festlegst, verwendet die API stattdessen diese URL.
   Request headers	Die Header, die die API mit jeder Anfrage sendet, zum Beispiel den API-Key-Header deiner Observability-Plattform. Lege Anmeldedaten nur in Header-Werten ab. Nach dem Speichern zeigt die Console die Werte nicht mehr an.
   Content mode	Metadata only oder Full content. Siehe wie sich die Content-Modi unterscheiden.
   Workspaces	Die Workspaces, deren Spans das Ziel empfängt: All, Selected oder All except. Siehe Workspaces für ein Ziel wählen.
   OTLP traces endpoint URL	Optional, unter Advanced settings. Die vollständige URL des Traces-Endpunkts deiner Observability-Plattform, zum Beispiel https://gateway.example.com/custom/traces. Lege sie fest, wenn die Plattform Traces unter einer anderen URL als der OTLP endpoint URL plus /v1/traces empfängt. Sie muss denselben Host wie die OTLP endpoint URL haben.
   Maximum content size in MB	Optional, unter Advanced settings, wenn der Content-Modus Full content ist. Die maximale Menge an Inhalt, die die API in jedem Span sendet. Die Console füllt das Feld je nach gewähltem Provider aus. Passe den Wert an das an, was deine Observability-Plattform akzeptiert. Lass das Feld leer, um so viel zu senden, wie die API zulässt. Siehe Inhaltsgrenzen.

3. Klicke zum Speichern auf Add destination.

4. Klicke im Menü More actions des Ziels auf Test. Eine Meldung zeigt an, ob der Test-Span an deinen Collector zugestellt wurde oder warum die Zustellung fehlgeschlagen ist (siehe Zustellungsfehler).

5. Prüfe, ob der Span anthropic.test in deiner Observability-Plattform angekommen ist.

Admin API und CLI

Du kannst ein Ziel auch über die Admin API statt über die Console hinzufügen. Melde dich in der CLI als Admin an oder verwende einen Admin-API-Key in ANTHROPIC_API_KEY. Sende die Anfragen bei Claude Platform on AWS stattdessen an https://aws-external-anthropic.{region}.api.aws, signiert mit deinen AWS-Zugangsdaten wie unter Anfragen stellen. Dort legt deine IAM-Richtlinie fest, wer Ziele verwalten kann. Eine Anfrage kann nur die Workspaces deines AWS-Kontos in dieser Region enthalten.

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)

Eine create-Anfrage übernimmt die Einstellungen der Console außer Provider, gib also die Endpunkt-URL und die Header deiner Observability-Plattform selbst ein. Setze traces.max_content_bytes in Bytes, damit es zu dem passt, was deine Observability-Plattform akzeptiert (siehe Inhaltsgrenzen). Um Ziele aufzulisten, zu ändern oder zu löschen oder einen einzelnen Workspace hinzuzufügen oder zu entfernen, verwende die anderen Methoden der API für Telemetrie-Ziele.

2. Workspaces für ein Ziel wählen

Ein Ziel empfängt die Spans der Workspaces, die es abdeckt. Wähle sie aus, wenn du das Ziel hinzufügst. Wähle für Workspaces eine der folgenden Optionen:

• All: Jeder Workspace in der Organisation, einschließlich des Default Workspace und später erstellter Workspaces.
• Selected: Nur die Workspaces, die du auswählst.
• All except: Wie All, aber ohne die Workspaces, die du auswählst.

Wähle bei Selected oder All except die Workspaces im Suchfeld aus, das unter den Optionen erscheint. Um die Workspaces eines Ziels später zu ändern, öffne sein Menü More actions auf der OpenTelemetry-Einstellungsseite, während der Filter Workspace All anzeigt. Klicke auf Edit und wähle dann eine andere Workspaces-Option oder ändere die Workspaces im Suchfeld.

Wenn du die Entwickler-Rolle in der Organisation und die Workspace Admin-Rolle in einem Workspace hast, kannst du diesen Workspace zu einem Selected-Ziel hinzufügen oder ihn daraus entfernen. Stelle den Filter Workspace auf diesen Workspace ein und öffne dann das Menü More actions des Ziels. Bei Claude Platform on AWS gibt es in der Console keine Workspace Admin-Rolle. Dort entscheidet deine IAM-Richtlinie, wer einen Workspace einem Ziel hinzufügen oder daraus entfernen kann.

Die API sendet Spans an jedes aktivierte Ziel, das den Workspace, in dem die Anfrage oder Session ausgeführt wird, abdeckt.

3. Prüfen, ob Spans ankommen

1. Wähle in der Console einen Workspace aus, den das Ziel abdeckt, und sende eine Messages-API-Anfrage im Playground. Du kannst auch eine Messages-API-Anfrage aus deiner Anwendung senden oder eine Managed-Agents-Session in diesem Workspace starten. Um eine Session zu starten, kannst du den Schritten in Erste Schritte mit Claude Managed Agents folgen.
2. Prüfe in der Console auf der OpenTelemetry-Einstellungsseite, ob die Spalte Delivery des Ziels Healthy anzeigt. Das kann etwa eine Minute dauern.
3. Filtere in deiner Observability-Plattform nach service.name = claude-platform, um die Spans der Anfrage zu finden.

Wenn die Spalte Failing anzeigt, halte den Mauszeiger darüber, um den letzten Fehler zu sehen. Die wahrscheinliche Ursache findest du unter Zustellungsfehler.

4. API-Spans mit deinen eigenen Traces verbinden

Standardmäßig befinden sich die API-Spans einer Messages-API-Anfrage oder einer Managed-Agents-Session in eigenen Traces. Verbinde sie mit den Traces deiner Anwendung, sodass sie unter deinen eigenen Spans verschachtelt werden.

Die API liest den Trace-Kontext jeder Anfrage aus dem W3C-traceparent-Header. Wenn das Sampled-Flag im Header aus ist, erzeugt die API weder den Span der Anfrage noch die Spans darunter. Claude Platform on AWS unterstützt diesen Header noch nicht. Die Spans für Anfragen, die du dorthin sendest, starten immer eigene Traces, auch wenn das Sampled-Flag aus ist.

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"}],
            },
        ],
    )

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",
}
# Kopiere den Trace-Kontext des aktiven Spans in die Request-Header.
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"}],
            },
        ],
    },
)

Die Messages API gibt den Trace auch an deinen MCP-Server weiter, wenn du ihn mit dem MCP-Connector verbindest, sodass er seine eigenen Spans unter die API-Spans setzen kann. Jede Anfrage und Benachrichtigung, die die API an deinen MCP-Server sendet, enthält einen W3C-traceparent in params._meta. In einer tools/call-Anfrage verweist er auf den anthropic.mcp_tool_use-Span dieser Tool-Nutzung. In den anderen Nachrichten verweist er auf den anthropic.messages.create-Span. Für eine Anfrage, die die API nicht tracet, etwa eine, deren traceparent-Header das Sampled-Flag deaktiviert hat, sendet die API keinen traceparent.

Nächste Schritte

Zustellung und Status

Die folgenden Regeln gelten für die Spans, die die API an deine Ziele sendet.

• Mindestens einmal: Ein Ziel kann denselben Span mehr als einmal erhalten. Um Duplikate zu entfernen, verwende die Trace-ID und die Span-ID.
• Best Effort: Ein Span kann vor der Zustellung verloren gehen. Die API kann einen verlorenen Span nicht erneut senden.
• Komprimierung: Die API komprimiert die erste Anfrage jeder Zustellung mit gzip und setzt den Header Content-Encoding: gzip. Wenn dein Endpunkt diese Anfrage mit einer 400- oder 415-Antwort beantwortet, sendet die API dieselben Spans sofort erneut ohne Komprimierung.
• Wiederholungen: Nach einem Timeout, einem Verbindungs-, TLS- oder DNS-Fehler oder einer 408-, 429- oder 5xx-Antwort versucht die API die Zustellung später erneut, eine begrenzte Anzahl von Malen. Bei anderen Fehlern wiederholt sie die Zustellung nicht.
• Timeouts: Für jede Anfrage muss dein Endpunkt den TLS-Handshake innerhalb von 5 Sekunden abschließen und die Antwort-Header innerhalb von 5 Sekunden senden. Jede Zustellung läuft nach insgesamt 10 Sekunden ab, einschließlich des erneuten Sendens ohne Komprimierung.
• User Agent: Jede Anfrage hat den Header User-Agent: Claude-Platform.

Die Spalte Delivery zeigt den Zustand jedes Ziels. Der Zustand kann bis zu einer Minute verzögert sein.

Die API deaktiviert ein Ziel, wenn:

• Der Endpunkt eine 3xx-Weiterleitung sendet.
• Der Hostname des Endpunkts zu einer IP-Adresse aufgelöst wird, die nicht öffentlich ist.
• Alle Zustellungen 24 Stunden lang fehlschlagen.

Die API sendet keine Spans an ein deaktiviertes Ziel. Um den Export fortzusetzen, behebe die Ursache. Klicke dann, während der Filter Workspace auf der OpenTelemetry-Einstellungsseite All anzeigt, im Menü More actions des Ziels auf Enable. Der Export startet innerhalb von etwa einer Minute erneut.

Um ein Ziel zu ändern, öffne sein Menü More actions, während der Filter Workspace All anzeigt. Klicke dann auf Edit, Disable, Enable oder Delete. Wenn du den Host der OTLP endpoint URL änderst, gib die Header-Werte erneut ein. Wenn das Ziel eine OTLP traces endpoint URL hat, gib ihr denselben neuen Host oder leere sie.

Limits

Fehlerbehebung

Zustellungsfehler

Wenn eine Zustellung fehlschlägt, zeigt die Spalte Delivery Failing an. Halte den Mauszeiger darüber, um den Fehler zu sehen, und finde dann die wahrscheinliche Ursache:

Compatibility