AdminOpenTelemetry

OpenTelemetry für die Claude API

Copy page



Verfolge deine Messages-API-Anfragen, Tool-Nutzungen und Managed-Agents-Sessions mit OpenTelemetry-Spans aus dem Claude SDK und der Claude API.

Die Claude API und das SDK können deine Messages-API-Anfragen, Tool-Nutzungen und Managed-Agents-Sessions mit OpenTelemetry tracen. Du kannst diese Traces in der Observability-Plattform ansehen, die du bereits hast. Nutze sie, um fehlgeschlagene oder langsame Anfragen zu debuggen, Token-Ausgaben und Latenz zu verfolgen und Evals aus echtem Traffic zu erstellen. Du kannst außerdem jede Anfrage in den eigenen Traces deiner Anwendung sehen, verknüpft mit dem Benutzer oder der Funktion, die sie gesendet hat.

OpenTelemetry ist ein herstellerneutraler Standard, den die meisten Observability-Plattformen unterstützen. Ein trace (Trace) ist die vollständige Aufzeichnung einer Anfrage durch dein System. Ein span (Span) ist ein Schritt in einem Trace, etwa eine Modellanfrage oder eine Tool-Nutzung. Die API und das SDK verwenden Attribute aus den GenAI semantic conventions, sodass Plattformen, die diese Konventionen unterstützen, die Spans ohne zusätzliche Einrichtung erkennen können.

Erste Schritte

Du kannst SDK-Tracing, API-Tracing oder beides einrichten. Richte beide ein, um die SDK- und API-Spans einer Anfrage in einem Trace zu sehen, wie in den Beispiel-Traces. Bei Anfragen an Claude Platform on AWS befinden sich die API-Spans stattdessen in eigenen Traces.

Für Claude Code, das Agent SDK oder Cowork siehe Claude Code-Monitoring, Agent SDK-Observability oder Cowork-Aktivitätsüberwachung.

Traces an eine Partnerplattform senden

Sende Traces an jede Observability-Plattform, die OTLP akzeptiert, einschließlich dieser Partner:

Content-Modi

Jedes Ziel und jeder SDK-Client hat einen Content-Modus, der festlegt, ob Spans Modell-Prompts und -Antworten enthalten. Lege ihn fest, wenn du ein Ziel hinzufügst oder das SDK konfigurierst.

• Metadata only (metadata_only im SDK): Der Standard. Spans enthalten Bezeichner, Zeitangaben, Status, Token-Anzahlen und Text, den du festlegst, etwa die Namen und Beschreibungen deiner Agenten und Tools sowie die Namen deiner MCP-Server.
• Full content (content im SDK): Die größte Sichtbarkeit. Spans enthalten Modell-Prompts und -Antworten sowie alles aus Metadata only.

Mit Full content kannst du außerdem sehen, warum ein Lauf fehlgeschlagen oder langsam war, vollständige Konversationen lesen und Evals aus echten Traces erstellen. In der OpenTelemetry-Span-Referenz sind Attribute, die Prompts und Antworten enthalten, mit Content gekennzeichnet.

Wenn deine Organisation mit Anthropic eine HIPAA-, FERPA- oder K-12-Einschränkung für den Datenumgang hat, exportieren Ziele unabhängig von ihrem Content-Modus nur Metadaten. SDK-Spans sind davon nicht betroffen.

Mit Zero Data Retention kannst du weiterhin Full content verwenden. Bei Messages-API-Anfragen hält die API die exportierten Inhalte nur im Arbeitsspeicher, bis sie sie an das Ziel übermittelt. Claude Managed Agents kommt für Zero Data Retention nicht infrage, und seine Datenaufbewahrung bleibt unverändert, wenn du OpenTelemetry verwendest.

Inhaltsgrenzen

Mit Full content enthält jeder Span standardmäßig bis zu 0,75 MB Inhalt. Das reicht für ein Kontextfenster von 200k Token mit englischem Text und bleibt unter dem Anfragelimit von 1 MB vieler Observability-Plattformen und Proxys. Wenn du eine Partnerplattform als Provider wählst, legt die Console ein Limit fest, das die Plattform akzeptiert.

Wenn der Inhalt das Limit überschreitet, kürzt ihn das SDK oder die API und setzt anthropic.content.truncated auf true. Bei Anfrage-Spans werden zuerst der System-Prompt und die ältesten Nachrichten entfernt, bei Tool-Spans werden Blöcke vom Ende des Ergebnisses her entfernt. Bilder und Dokumente erscheinen nur mit ihrem Typ.

Ändere das Limit in diesen Fällen:

• Deine Observability-Plattform akzeptiert größere Payloads: Erhöhe oder entferne das Limit, damit lange Prompts und Antworten vollständig bleiben. Ein volles 1M-Token-Kontextfenster benötigt etwa 4 MB.
• Deine Observability-Plattform oder ein vorgeschalteter Proxy lehnt große Anfragen ab: Senke das Limit.

Lege im SDK traces.max_content_bytes fest. Setze in der Console Content mode auf Full content, wenn du ein Ziel hinzufügst, und lege dann unter Advanced settings Maximum content size in MB fest.

Beispiel-Traces und wie du sie liest

Eine Messages-API-Anfrage

Unter dem API-Span einer Anfrage, die eine Nachricht erstellt, fügt die API einen Span für jede Modellanfrage und einen Tool-Span für jede Nutzung eines Server-Tools oder eines MCP-Connector-Tools hinzu, das die API ausführt.

In diesem Beispiel ruft deine Anwendung den Tool Runner auf, den SDK-Helfer, der deine Tools ausführt und ihre Ergebnisse an Claude zurücksendet. Jede Anfrage, die der Tool Runner sendet, hat einen Client-Span vom SDK und einen Server-Span von der API. Die Spans erscheinen in der folgenden Reihenfolge:

1. Deine Anwendung startet den answer_question-Span und ruft darin den Messages Tool Runner auf (dargestellt als anthropic.messages.tool_runner-Span).
2. Der Tool Runner sendet die erste Anfrage (dargestellt als erster anthropic.messages.create-Client-Span und die Spans darunter). In dieser Anfrage führt die API das Websuche-Tool zwischen zwei Modellanfragen aus.
3. In der zweiten Modellanfrage fordert das Modell die Nutzung des benutzerdefinierten Tools get_weather an, daher endet die erste Anfrage.
4. Der Tool Runner führt get_weather aus (dargestellt als anthropic.custom_tool_use get_weather-Span).
5. Der Tool Runner sendet die zweite Anfrage mit dem Tool-Ergebnis (dargestellt als zweiter anthropic.messages.create-Client-Span und die Spans darunter).
6. In der zweiten Anfrage gibt das Modell die endgültige Antwort.

Das SDK in deiner Anwendung erzeugt den anthropic.messages.tool_runner-Span, den anthropic.custom_tool_use-Span und den Client-Span jeder Anfrage. Um diese Spans zu erhalten, richte SDK-Tracing ein.

Jede Anfrage hat ihre Token-Nutzung auf mehreren ihrer Spans. Um jedes Token nur einmal zu zählen, siehe Zählen von Token.

Mit Full content enthält der anthropic.messages.create-Server-Span den Prompt und die Antwort. Der System-Prompt steht in gen_ai.system_instructions, die Nachrichten der Anfrage in gen_ai.input.messages und die Antwort in gen_ai.output.messages.

Für jeden Span und seine Attribute siehe die OpenTelemetry-Span-Referenz.

Eine Managed Agents-Session

Eine Session hat einen Span für jede Anfrage an die Sessions API und einen Turn-Span für jeden Agent-Turn. Ein Turn, den eine Anfrage startet, ist ein Kind des Spans dieser Anfrage. Ein Turn enthält einen Span für jede Modellanfrage und jedes Tool, das die API ausführt, außer in den Fällen, die in der Tool-Span-Referenz aufgeführt sind. Er enthält außerdem einen Span für jede Outcome-Evaluierung.

Dieses Beispiel verfolgt eine Chat-Anfrage, in der deine Anwendung eine Nachricht an eine Session sendet und ein benutzerdefiniertes Tool ausführt. Der Trace enthält Spans sowohl von deiner Anwendung als auch von der API, in der folgenden Reihenfolge:

1. Deine Anwendung empfängt eine POST /chat-Anfrage von einem Benutzer.
2. Deine Anwendung startet den Session-Tool-Runner des SDK, der die Events der Session auflistet und streamt (dargestellt als die Spans anthropic.sessions.events.stream und anthropic.sessions.events.list).
3. Deine Anwendung sendet die Nachricht des Benutzers an die Session, indem sie sessions.events.send aufruft.
4. Ein Turn beginnt und umfasst Modellanfragen, eine bash-Tool-Nutzung und einen Turn in einem anderen Thread (dargestellt als der erste anthropic.session.turn-Span und die Spans darunter).
5. Das Modell fordert die Nutzung des benutzerdefinierten Tools list_issues an, daher endet der Turn mit dem Stop-Grund requires_action.
6. Der Session-Tool-Runner führt list_issues aus (dargestellt als der Span anthropic.custom_tool_use list_issues) und sendet dessen Ergebnis, indem er sessions.events.send aufruft.
7. Ein zweiter Turn beginnt mit dem Tool-Ergebnis (dargestellt als der letzte anthropic.session.turn-Span).

Das SDK in deiner Anwendung erzeugt den anthropic.custom_tool_use-Span und den Client-Span jeder Anfrage. Um diese Spans zu erhalten, richte SDK-Tracing ein.

Die Spans einer Session können sich in mehreren Traces befinden, zum Beispiel wenn du eine spätere Anfrage aus einem neuen Root-Trace sendest. Mit aktiviertem Multiagent kann eine Session außerdem mehrere Threads haben. Um die benötigten Spans zu finden, gruppiere sie nach einer ID.

• Ein Thread: Gruppiere Spans nach gen_ai.conversation.id, das die Session-Thread-ID enthält. Sortiere sie nach Startzeit, um den Thread als Transkript zu lesen.
• Eine ganze Session mit all ihren Threads: Gruppiere Spans nach anthropic.session.id, über Traces hinweg.

Mit Full content kannst du den Inhalt einer Session aus ihren Spans lesen.

• Um den Inhalt eines Turns zu lesen, verwende seinen Turn-Span. Der System-Prompt befindet sich in gen_ai.system_instructions auf dem ersten Turn-Span eines Threads, die Eingabe in gen_ai.input.messages (deine Nachrichten und Tool-Ergebnisse, system.message-Events und Nachrichten aus anderen Threads) und die Ausgabe in gen_ai.output.messages (die Nachrichten, Tool-Nutzungen und Tool-Ergebnisse des Agenten).
• Um die Argumente und das Ergebnis einer Tool-Nutzung zu sehen, lies ihren Tool-Span. Die Argumente befinden sich in gen_ai.tool.call.arguments und das Ergebnis in anthropic.tool_result.content.

Zu jedem Span und seinen Attributen siehe die OpenTelemetry-Span-Referenz.

Zählen von Token

Um jedes Token nur einmal zu zählen, summiere für jede Anfrage nur die Spans einer einzigen Quelle. Wenn eine Messages API-Anfrage sowohl einen SDK-Span als auch einen API-Span hat, summiere ihre API-Spans. Beide heißen anthropic.messages.create, unterscheide sie daher anhand ihrer Art: Der SDK-Span ist CLIENT und sein Kind, der API-Span, ist SERVER.

Summiere für jede Quelle nur die folgenden Spans, da sich einige Nutzungsattribute auf mehr als einer Ebene der API-Spans wiederholen:

• SDK-Spans: Summiere die anthropic.messages.create-Spans. Wenn eine Anfrage Compactions hat, addiere außerdem anthropic.usage.compaction.input_tokens und anthropic.usage.compaction.output_tokens des Spans, da die gen_ai.usage.*-Attribute keine Compaction-Token enthalten. Wenn ein Fallback-Modell eine Anfrage bedient hat, enthält ihr Span nur die Nutzung des Modells, das die Antwort geliefert hat.
• API-Spans für eine Messages API-Anfrage: Summiere entweder die anthropic.messages.create-Spans oder ihre anthropic.model_request-Spans, nicht beide. Wenn eine Anfrage Compactions hat, addiere außerdem ihre anthropic.compaction-Spans. Addiere nicht zusätzlich die anthropic.usage.compaction.*-Attribute des anthropic.messages.create-Spans, da sie dieselben Token enthalten.
• API-Spans für eine Managed Agents-Session: Summiere die Spans anthropic.model_request und anthropic.session.outcome_evaluation.

Spans können mehr als einmal ankommen, zum Beispiel wenn eine Zustellung wiederholt wird. Wenn deine Observability-Plattform keine Duplikate entfernt, zähle jeden Span anhand seiner Trace-ID und Span-ID nur einmal.

gen_ai.usage.input_tokens enthält bereits die aus dem Prompt-Cache gelesenen und in ihn geschriebenen Token, addiere die Cache-Attribute also nicht dazu. Alle Nutzungsattribute findest du unter Token-Nutzung.