Zum Hauptinhalt springen

First-Party-OpenTelemetry-Tracing: zwei Pfade, ein Trace

Experte

Den größten Teil von 2026 hieß einen Claude-API-Aufruf zu tracen, den Span selbst zu schreiben: einen Span öffnen, messages.create aufrufen, usage auf Attribute kopieren, den Span schließen. Agent-Observability ist die Seite darüber, wie man das gut macht — und sie bleibt die Seite darüber, was die Namen bedeuten.

Diese Seite handelt von dem Teil, der sich geändert hat. API und SDK senden diese Spans jetzt selbst, in der Beta, und sie senden deutlich mehr, als Sie von Hand geschrieben haben: einen Span pro Modellanfrage innerhalb einer API-Anfrage, einen Span pro Server-Tool, das die API für Sie ausgeführt hat, einen Span pro Compaction, einen Span pro Managed-Agents-Turn. Dinge, die auf Anthropics Seite des Wire passieren und die eine Handinstrumentierung strukturell nicht sehen kann.

Es gibt zwei unabhängige Pfade, das einzuschalten, und das teuerste Missverständnis ist, dass sie sich überlappen. Aktivieren Sie beide, ohne einen Absatz der Doku zu lesen, und jede Messages-Anfrage erscheint doppelt, mit demselben Span-Namen, und Ihre Token-Dashboards verdoppeln sich.

What you'll learn
  • Zwischen SDK-Tracing, API-Tracing oder beidem wählen — und genau wissen, was jedes sehen kann und was nicht
  • Jeden Pfad einrichten: einen Tracer-Provider in Ihrem Code, ein Ziel in der Console oder über die Admin API
  • Token über überlappende Spans hinweg korrekt summieren — die eine Regel, die Doppelzählung verhindert
  • Einen Content-Modus bewusst wählen und wissen, was Ihre Wahl überschreibt (HIPAA/FERPA/K-12, Zero Data Retention)
  • API-Spans mit traceparent in die Traces Ihrer Anwendung einbinden — und das Sampled-Flag vermeiden, das sie löscht
  • Die Zustellregeln überstehen: At-least-once, Best-Effort und automatische Deaktivierung nach 24 Stunden Fehlschlägen

Die zwei Pfade​

Es sind nicht zwei Wege, dasselbe zu tun. Sie sehen verschiedene Hälften des Laufs.

Was Sie bekommenSDK-TracingAPI-Tracing
Anfragen an Messages API und Sessions APIjaja
Token-Nutzungjaja
Jede Modellanfrage innerhalb einer API-Anfrage—ja
Managed-Agents-Turns—ja
Server-Tools und MCP-Connector-Tools, von der API ausgeführt—ja
Ihre eigenen Client-Tools, vom Tool Runner ausgeführtja—
Tools in einer selbst gehosteten Sandboxja—
Andere Anfragen, etwa Datei-Uploadsja—
Wie Sie es einrichtenCodeConsole oder Admin API
Wer es einrichten kannjeder Entwicklerein Admin
Welche Clients es abdecktnur Clients, die das SDK nutzenjeder Client, auch curl

Die Aufteilung folgt einer Linie: Das SDK sieht, was Ihr Prozess tut, die API sieht, was Anthropics Seite tut. Ein Server-Tool wie Web-Suche läuft innerhalb der API-Anfrage — Ihr Prozess beobachtet es nie, also erzeugt nur API-Tracing diesen Span. Ihre eigene Funktion get_weather läuft in Ihrem Prozess — nur SDK-Tracing erzeugt diesen.

Deshalb ist „beides“ für die meisten Produktions-Setups die echte Antwort, und deshalb ist die Überlappungsregel unten kein Randfall.

Lesen Sie diese Form sorgfältig, denn sie enthält die Falle. anthropic.messages.create erscheint bei einer Konversation mit zwei Anfragen viermal: zweimal vom SDK (Kind CLIENT) und zweimal von der API (Kind SERVER), wobei jeder API-Span an seinen SDK-Span gehängt ist. Es sind keine Duplikate im Sinne einer erneuten Zustellung — es sind zwei legitime Beobachtungen derselben Anfrage, von beiden Enden.

SDK-Tracing einrichten​

SDK-Spans brauchen keine Berechtigungen und keinen Console-Zugang. Das SDK nutzt den Tracer-Provider, den Ihre Anwendung bereits registriert hat, es gibt also keinen Anthropic-spezifischen Exporter einzurichten.

Guided walkthrough1 of 4
  1. Spans sind in den aktuellen SDKs für Python, TypeScript, C#, Go, Java, PHP und Ruby enthalten. Bei Java ist das Minimum `anthropic-java` 2.73.0. Pinnen Sie die Version — laut Beta-Hinweis kann ein neuer SDK-Release einen Span, ein Attribut, eine Option oder eine Umgebungsvariable umbenennen.

Minimal funktionierendes SDK-Tracing — zuerst Console-Exporter (Python)

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Register BEFORE the first traced call. Swap ConsoleSpanExporter for an
# OTLP exporter once you can see spans in the terminal.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

# Record prompts and responses, and label this conversation.
client = Anthropic(open_telemetry={"traces": {"content_mode": "content"}})

tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("answer_question"):
  message = client.with_options(
      open_telemetry={**client.open_telemetry, "conversation_id": "conv_42"}
  ).messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello, Claude"}],
  )

Die SDK-Optionen, die man kennen sollte​

Option (Python-Schreibweise)UmgebungsvariableStandard
traces.content_modeANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODEmetadata_only
traces.max_content_bytesANTHROPIC_OPEN_TELEMETRY_TRACES_MAX_CONTENT_BYTES0,75 MB
conversation_id—keine
tracer_provider—der registrierte globale Provider
propagationANTHROPIC_OPEN_TELEMETRY_PROPAGATIONan
open_telemetry (Aus-Schalter)ANTHROPIC_OPEN_TELEMETRYan

Zwei Verhaltensweisen hier kosten Sie je eine Stunde, wenn Sie unvorbereitet auf sie treffen:

  • Das Übergeben von open_telemetry an den Client überschreibt die Umgebungsvariablen als Ganzes, einschließlich verschachtelter Schlüssel. Jeder Schlüssel, den Sie im Objekt weglassen, fällt stillschweigend auf seinen Tabellenstandard zurück, selbst wenn seine Variable gesetzt ist. Bauen Sie das Objekt aus dem bestehenden auf, nicht von Grund auf.
  • Bei TypeScript mit @opentelemetry/instrumentation-undici — das @opentelemetry/auto-instrumentations-node mitbringt — setzen Sie propagation: false. Ein Fehler in diesem Paket fügt jeder Anfrage einen zweiten traceparent-Header hinzu, was den Trace-Kontext ungültig macht und die Verknüpfung stillschweigend bricht.

API-Tracing einrichten​

API-Tracing braucht überhaupt keine Codeänderung. Sie registrieren ein Ziel — den OTLP-Endpunkt Ihrer Observability-Plattform plus Zugangsdaten —, und die API sendet Spans dorthin.

Was Sie vor dem Start brauchen:

  • Die Admin-Rolle in der Console-Organisation. Die Entwickler-Rolle kann Ziele ansehen, aber nicht erstellen oder ändern.
  • Einen OTLP/HTTP-Endpunkt, der Protobuf akzeptiert, über HTTPS, auf Port 443. Das ist die Anforderung, die Selbsthoster trifft: Ein Standard-OpenTelemetry-Collector lauscht für OTLP/HTTP auf Port 4318, Sie brauchen also einen Load Balancer, Reverse Proxy oder einen umkonfigurierten Receiver davor. Es gibt keine gRPC-Option und keinen anderen Port als 443.
  • Zugangsdaten für diesen Endpunkt, die in Request-Header kommen. Die Console zeigt die Werte nach dem Speichern nicht wieder an.

Ein Telemetrie-Ziel mit der Admin API erstellen (curl)

curl --fail-with-body -sS "https://api.anthropic.com/v1/organizations/telemetry_destinations" \
-H "x-api-key: $ANTHROPIC_ADMIN_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"}
}'

Beachten Sie die Form der Endpunkt-URL: Geben Sie die Basis-OTLP-URL an und lassen Sie die API /v1/traces selbst anhängen. Ein Pfadpräfix ist erlaubt. Wenn Ihre Plattform Traces ganz woanders entgegennimmt, setzen Sie die optionale Traces-Endpunkt-URL — sie muss aber denselben Host haben.

Drei Einstellungen verdienen eine bewusste Entscheidung statt eines Standards:

  • Workspaces — all, selected oder all except. all schließt später erstellte Workspaces ein, was meist das ist, was Sie wollen, und gelegentlich genau das, was Sie nicht wollen. Ein Ziel erhält nur Spans aus dem Workspace, in dem die Anfrage oder Session tatsächlich lief.
  • Content-Modus — unten behandelt.
  • Maximale Content-Größe — gilt nur im Full-Content-Modus. Die Wahl eines gelisteten Partners in der Console füllt einen Wert vor, den diese Plattform akzeptiert; bei Custom sind Sie auf sich gestellt.

Dann prüfen, in dieser Reihenfolge: Senden Sie über das Menü des Ziels einen Test-Span und bestätigen Sie, dass ein Span anthropic.test ankommt; senden Sie eine echte Anfrage im gewählten Workspace; prüfen Sie, dass die Spalte Delivery Healthy zeigt; filtern Sie Ihre Plattform auf service.name = claude-platform. Rechnen Sie bei jedem Schritt mit etwa einer Minute — sowohl Zieländerungen als auch die Health-Spalte hinken ungefähr so viel hinterher.

Content-Modi und was Ihre Wahl überschreibt​

Jedes Ziel und jeder SDK-Client hat einen von zwei Content-Modi.

  • Nur Metadaten (metadata_only) — der Standard. IDs, Timing, Status, Token-Zahlen und Text, den Sie selbst gewählt haben: Agentennamen, Tool-Namen und -Beschreibungen, MCP-Servernamen.
  • Voller Inhalt (content) — alles oben plus Modell-Prompts und -Antworten. In der Span-Referenz tragen diese Attribute ein Content-Label: gen_ai.system_instructions, gen_ai.input.messages, gen_ai.output.messages, gen_ai.tool.call.arguments, anthropic.tool_result.content.

Voller Inhalt macht Traces für das nutzbar, was Teams tatsächlich wollen — eine gescheiterte Konversation lesen oder Evals bauen aus echtem Traffic. Er verschiebt aber auch Ihre Prompts und die Eingaben Ihrer Nutzer in ein zweites System, unter Aufbewahrung und Zugriffskontrollen dieses Anbieters statt Ihrer. Dieselbe Abwägung wie bei was Ihr Agent hochlädt: Das Einschalten gibt Ihrem Observability-Anbieter ungefähr die Freigabe, die Ihre Anwendungsdaten haben.

Zwei Überschreibungen sollte man sich merken, denn beide erzeugen verwirrende Support-Tickets:

  • Eine HIPAA-, FERPA- oder K-12-Datenschutzbeschränkung bei Anthropic zwingt Ziele auf nur Metadaten, was immer das Ziel sagt. SDK-Spans sind nicht betroffen — Ihr eigener Prozess kann weiter Inhalt senden. Das Symptom lautet also: „Full Content ist an, die Console bestätigt es, und die Prompts erscheinen nur an den CLIENT-Spans.“
  • Zero Data Retention ist mit vollem Inhalt vereinbar. Bei Messages-API-Anfragen hält die API exportierten Inhalt bis zur Zustellung nur im Arbeitsspeicher. Managed Agents ist ohnehin nicht ZDR-berechtigt, und seine Aufbewahrung bleibt durch die Nutzung von OpenTelemetry unverändert.

Content-Limits und Kürzung​

Jeder Span hält standardmäßig bis zu 0,75 MB Inhalt — gewählt, damit ein 200k-Token-Kontextfenster mit englischem Text hineinpasst und zugleich unter dem 1-MB-Anfragelimit bleibt, das bei Observability-Plattformen und Proxys üblich ist. Ein volles 1M-Token-Fenster braucht etwa 4 MB.

Überschreitet der Inhalt das Limit, wird der Span gekürzt und anthropic.content.truncated auf true gesetzt. Die Reihenfolge des Weglassens ist spezifiziert, und sie ist wichtig für alle, die Evals aus Traces bauen:

  • Request-Spans lassen zuerst den System-Prompt weg, dann die frühesten Nachrichten.
  • Tool-Spans lassen Blöcke vom Ende des Ergebnisses weg.
  • Bilder und Dokumente erscheinen nur als ihr Typ — nie als Bytes.

Eine naive Pipeline „jeden Trace als Eval-Fall wiedergeben“ füttert Sie also stillschweigend mit Konversationen ohne System-Prompt, sofern Sie nicht auf anthropic.content.truncated filtern. Machen Sie diesen Filter zur ersten Zeile der Pipeline, nicht zu einer späteren Entdeckung.

Die eine Regel: jedes Token einmal zählen​

Das ist der Abschnitt, den man zweimal lesen sollte. Token-Nutzungsattribute erscheinen absichtlich an mehreren Spans pro Anfrage, weil jeder Span seinen eigenen Schritt meldet. Alles zu summieren, was Sie empfangen, überzählt; die falsche Ebene zu summieren, unterzählt.

Guided walkthrough1 of 5
  1. Wenn eine Messages-Anfrage sowohl einen SDK-Span als auch einen API-Span hat, summieren Sie die API-Spans. Beide heißen `anthropic.messages.create`, Sie können also nicht nach Namen filtern — unterscheiden Sie sie nach Span-Kind: Der SDK-Span ist CLIENT, sein Kind-API-Span ist SERVER. Auch Filtern auf `service.name` = `claude-platform` funktioniert.

Noch etwas, das keine Zählregel ist, Sie aber vor einer falschen Zahl bewahrt: gen_ai.usage.input_tokens enthält bereits Cache-Reads und Cache-Writes. gen_ai.usage.cache_read.input_tokens dazuzuaddieren zählt die billigsten Tokens, die Sie haben, doppelt. Was diese Tokens im Verhältnis zueinander kosten, siehe Prompt Caching.

Traces sind kein Abrechnungsbeleg

Anthropic sagt klar, dass exportierte Spans keine garantiert vollständige Aufzeichnung der Nutzung sind. Die Zustellung ist Best-Effort, ein Span kann also verloren gehen; und ein Aufrufer kann die Spans einer Anfrage komplett unterdrücken, indem er das Sampled-Flag in seinem traceparent ausschaltet. Für Abrechnung pro Key — einen geleakten Key erkennen, eine Rechnung abgleichen — nutzen Sie die Usage API, die auch Anfragen zählt, die gar keine Spans erzeugten. Traces sind für Debugging und Kosten-Zuordnung; sie sind nicht das Hauptbuch.

API-Spans in Ihre eigenen Traces einbinden​

Standardmäßig leben API-Spans in ihren eigenen Traces — technisch korrekt und fast nutzlos, weil Sie nicht erkennen können, welches Feature oder welcher Nutzer den Aufruf verursacht hat.

Die API liest den W3C-Header traceparent jeder Anfrage. Mit dem SDK bekommen Sie das gratis, solange Sie das SDK innerhalb Ihres eigenen Spans aufgerufen und den W3C-Trace-Context-Propagator registriert haben. (Wenn Ihre Anwendung auf B3 oder einen anderen Propagator standardisiert hat, fügen Sie W3C daneben hinzu — das SDK schreibt Header mit Ihrem Propagator.) Bei jedem anderen Client injizieren Sie den Kontext des aktiven Spans selbst in die Header, bevor Sie senden.

Dann gibt es das Flag, das alle überrascht:

Das Sampled-Flag ist ein Ein/Aus-Schalter für Spans, kein Hinweis

Ist das Sampled-Flag im eingehenden traceparent aus, sendet die API keinen Span für diese Anfrage und keinen der darunterliegenden Spans. Head-Sampling in Ihrer Anwendung entscheidet also, ob Anthropic-seitige Telemetrie überhaupt existiert. Ein Dienst mit 1 % Sampling, der API-Tracing aktiviert, erhält 1 % der Modellanfrage- und Server-Tool-Spans — und wird schließen, das Feature sei kaputt. Sampeln Sie entweder am Tail in Ihrem Collector oder erzwingen Sie das Sampled-Flag für die Pfade, die Sie getract haben wollen.

Die Propagation geht einen Hop weiter, als die meisten erwarten. Wenn die Messages API Ihren MCP-Server über den MCP-Connector aufruft, übergibt sie einen W3C-traceparent in params._meta, sodass ein Server, der ihn liest, eigene Spans unter die der API hängen kann. In einer tools/call-Anfrage ist dieser Parent der Span anthropic.mcp_tool_use; in anderen Nachrichten ist es anthropic.messages.create. Eine nicht getracte Anfrage sendet gar keinen traceparent. Auf der Client-Seite ist das Bild lückenhafter: Das Python-Paket mcp ab Version 2.0 und das C#-Paket ModelContextProtocol leiten den Trace-Kontext in _meta weiter; die MCP-SDKs für TypeScript, Go, Java, Ruby und PHP tun das nicht von selbst.

Zustellregeln, und wie ein Ziel stirbt​

Der API-seitige Export ist ein Push von Anthropics Infrastruktur zu Ihrem Endpunkt, das heißt, er hat eigene Fehlersemantik — näher an einem Webhook als an einem OTLP-Exporter in Ihrem Prozess.

EigenschaftVerhalten
DuplizierungAt least once. Nach Trace-ID + Span-ID deduplizieren.
VerlustBest Effort. Ein verlorener Span wird nie erneut gesendet.
KompressionDie erste Anfrage jeder Zustellung wird mit Content-Encoding: gzip gezippt. Bei 400 oder 415 werden dieselben Spans sofort unkomprimiert erneut gesendet.
WiederholungenBegrenzte Wiederholungen nach einem Timeout, einem Verbindungs-/TLS-/DNS-Fehler oder einem 408, 429 oder 5xx. Andere Fehler werden nicht wiederholt.
TimeoutsTLS-Handshake innerhalb von 5 s, Response-Header innerhalb von 5 s, 10 s insgesamt pro Zustellung — einschließlich des unkomprimierten Erneutsendens.
User-AgentUser-Agent: Claude-Platform. Nützlich für eine Allowlist-Regel.

Und drei Wege, wie die API ein Ziel deaktiviert, sodass der Export stoppt, bis ein Mensch es wieder aktiviert:

  1. Der Endpunkt liefert einen 3xx-Redirect. Redirects werden nicht verfolgt — richten Sie das Ziel auf die endgültige URL.
  2. Der Hostname des Endpunkts löst auf eine nicht öffentliche IP-Adresse auf. Es gibt keinen Tunnel in Ihr VPC; stellen Sie einen öffentlichen Collector bereit oder nutzen Sie eine verwaltete Plattform.
  3. Jede Zustellung scheitert 24 Stunden lang.

Der dritte ist die betriebliche Gefahr. Ein rotierter Observability-API-Key, den niemand bemerkt, wird zu einem Ziel, das einen Tag lang Failing ist und dann Disabled — und das Wiederaktivieren ist ein manueller Klick in der Console (mit dem Workspace-Filter auf All), keine automatische Wiederherstellung. Wenn Sie von dieser Seite auf eine Sache alarmieren, dann auf den Delivery-Status.

Limits pro Organisation​

LimitWert
Ziele, einschließlich deaktivierter10
Für ein Ziel ausgewählte Workspaces1.000
Request-Header pro Ziel20
Länge des Header-Namens128 Bytes
Länge des Header-Werts4.096 Bytes
Alle Header-Namen und -Werte zusammen16.384 Bytes
Länge der Endpunkt-URL2.048 Zeichen

Eine Managed-Agents-Session lesen​

Sessions brechen die Ein-Trace-Annahme, und die Lösung ist ein Gruppierungsschlüssel statt einer Trace-ID.

Die Spans einer Session können in mehreren Traces landen — eine spätere Anfrage, die von einem neuen Root-Trace gesendet wird, startet einen neuen — und bei Multiagent-Orchestrierung hat eine Session mehrere Threads. Also:

  • Ein Thread als Transkript — nach gen_ai.conversation.id (der Session-Thread-ID) gruppieren, nach Startzeit sortieren.
  • Eine ganze Session, alle Threads — nach anthropic.session.id gruppieren, über Traces hinweg.

Die Span-Formen lohnt es sich zu verinnerlichen, denn sie passen nicht zu den generischen GenAI-Konventionen, für die Sie vielleicht schon Dashboards haben. anthropic.session.turn trägt gen_ai.operation.name = invoke_agent und umspannt den running-Zustand eines Threads; ein Turn, den eine Anfrage gestartet hat, ist ein Kind des Spans dieser Anfrage, während ein Turn, der startet, weil ein anderer Thread geantwortet hat, gar keinen Parent hat. Im Full-Content-Modus enthält der Turn-Span den Inhalt des Threads: gen_ai.system_instructions nur beim ersten Turn eines Threads, gen_ai.input.messages, gen_ai.output.messages. Advisor-Threads sind absichtlich dünner — gen_ai.agent.name ist anthropic.advisor, und die Attribute für Anweisung und Eingabe fehlen.

Vier Fälle erzeugen gar keinen API-Tool-Span, und jeder hat schon jemanden glauben lassen, sein Tracing sei kaputt: ein Tool, das Ihre Anwendung ausführt (den Span sendet der SDK-Tool-Runner); ein Tool in einer selbst gehosteten Sandbox (den sendet der SDK-Environment-Worker, gruppiert unter anthropic.environment.work); ein Multiagent- oder Advisor-Tool; und eine Tool-Nutzung, die unter der Berechtigungsrichtlinie auto oder durch ein user.tool_confirmation-Event abgelehnt wurde. Abgelehnte Aufrufe hinterlassen keinen Tool-Span — wenn Sie prüfen, was ein Agent zu tun versucht hat, lesen Sie die Session-Events, nicht den Trace.

Häufige Fehler​

  • Jeden empfangenen anthropic.messages.create-Span summieren. Zwei legitime Beobachtungen pro Anfrage, gleicher Name. Filtern Sie zuerst nach Span-Kind oder service.name. Das ist der Fehler, der eine plausible, falsche, exakt verdoppelte Kostenzahl erzeugt.
  • Spans mit Ihrer üblichen Sampling-Rate erwarten. Ein ausgeschaltetes Sampled-Flag im traceparent unterdrückt die API-Spans vollständig. Head-Sampling in Ihrem Dienst ist Head-Sampling der Telemetrie von Anthropic.
  • Ein Ziel auf einen nackten Collector richten. OTLP/HTTP auf 4318 ist kein HTTPS-Endpunkt auf 443. Setzen Sie einen Proxy davor, sonst stellt das Ziel nie zu.
  • Full Content wie ein Logging-Flag behandeln. Es verlagert Prompts und Nutzereingaben zu Ihrem Observability-Anbieter. Entscheiden Sie es mit dem, der für Datenschutz zuständig ist, und wissen Sie, dass eine HIPAA/FERPA/K-12-Beschränkung es stillschweigend nur für API-Spans überschreibt.
  • Evals aus Traces bauen, ohne anthropic.content.truncated zu prüfen. Die Kürzung lässt zuerst den System-Prompt weg. Ihrem Eval-Korpus fehlt genau der Teil, der das Verhalten bestimmt hat.
  • Ein Failing-Ziel liegen lassen. 24 Stunden Fehlschläge deaktivieren es, und das Wiederaktivieren ist manuell. Alarmieren Sie auf den Delivery-Status, nicht auf das Span-Volumen — das Span-Volumen sieht gut aus, bis es null ist.
  • Diese Attributnamen in vierzig Panels hart codieren. Die Spans folgen den GenAI-Konventionen an einem bestimmten Commit (e57c543b, 24. September 2026) eines Repositorys ohne getaggten Release, und der Beta-Hinweis behält sich Umbenennungen vor. Die Mapping-Schicht-Gewohnheit aus Agent-Observability gilt hier mit besonderem Nachdruck.

Wohin die Spans gehen​

Jede Plattform, die OTLP akzeptiert, funktioniert. Anthropic dokumentiert Integrationsleitfäden mit Arize AI, Braintrust, Databricks, Datadog, Grafana Cloud, Honeycomb, Langfuse, LangSmith, New Relic, PostHog, Sentry und Splunk; die Wahl eines gelisteten Anbieters in der Console fragt nach den eigenen Zugangsdaten dieser Plattform und füllt eine akzeptierte Content-Größe vor, statt nach einem rohen Endpunkt und Headern zu fragen.

Für Claude Code, das Agent SDK und Cowork ist das ein anderes System mit anderen Schaltern — CLAUDE_CODE_ENABLE_TELEMETRY und Verwandte, behandelt in Agent-Observability. Hier Ziele zu aktivieren, bewirkt für sie nichts, und umgekehrt.

Check yourself

0/3
  1. Sie aktivieren sowohl SDK-Tracing als auch API-Tracing und summieren dann gen_ai.usage.input_tokens über jeden anthropic.messages.create-Span. Was passiert?
  2. Ihr Dienst head-sampelt 1 % der Traces, und Sie haben gerade ein Telemetrie-Ziel hinzugefügt. Warum kommen fast keine Modellanfrage-Spans an?
  3. Ein Ziel zeigt einen Tag lang Failing, weil der Observability-API-Key rotiert wurde. Was passiert als Nächstes?
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 14
Key takeaways
  • Zwei Pfade, zwei Hälften des Laufs: Das SDK sieht Ihren Prozess, die API sieht Anthropics Seite. Die meisten Produktions-Setups wollen beides.
  • Beide Pfade senden anthropic.messages.create für dieselbe Anfrage. Wählen Sie eine Quelle nach Span-Kind, bevor Sie irgendetwas summieren.
  • Innerhalb der API-Spans eine Ebene summieren — messages.create oder model_request, nie beide — und Compaction aus genau einer Stelle addieren.
  • Spans sind für Debugging und Zuordnung, nicht für Abrechnung: Die Zustellung ist Best-Effort, und ein ausgeschaltetes Sampled-Flag im traceparent löscht eine Anfrage komplett. Nutzen Sie die Usage API als Hauptbuch.
  • Das Sampled-Flag ist ein Ein/Aus-Schalter, kein Hinweis. Ein Dienst mit 1 % Sampling bekommt 1 % der Anthropic-seitigen Spans.
  • Full Content verlagert Ihre Prompts zu Ihrem Observability-Anbieter. Eine HIPAA/FERPA/K-12-Beschränkung überschreibt es nur für API-Spans — ein sehr verwirrendes Symptom, wenn man es nicht kennt.
  • Prüfen Sie anthropic.content.truncated, bevor Sie Evals aus Traces bauen: Die Kürzung lässt zuerst den System-Prompt weg.
  • Alarmieren Sie auf den Delivery-Status eines Ziels. 24 Stunden Fehlschläge deaktivieren es, und die Wiederherstellung ist ein manueller Klick.

Weiter​

  • Agent-Observability — was die gen_ai.*-Namen bedeuten, warum keiner davon stabil ist, und die Claude-Code-Telemetrie-Schalter, die diese Seite nicht abdeckt
  • Cache diagnostics — wenn die Spans einen unerwarteten Cache-Read zeigen, die Felder pro Anfrage, die erklären, warum
  • Managed agents — die Sessions, Turns und Threads, deren Spans Sie auf dieser Seite zu gruppieren lernen

Quellen & weiterführende Literatur​