OpenTelemetry mit dem Claude SDK verwenden

Mit OpenTelemetry kann das Claude SDK einen span (Span) für jede Anfrage ausgeben, die es sendet, und für jede Tool-Nutzung, die der Tool Runner ausführt. Du kannst diese Spans in deiner Observability-Plattform ansehen, eingebettet in deine eigenen Traces.

Das SDK erzeugt Spans in deiner Anwendung. Der OpenTelemetry-Exporter deiner Anwendung sendet sie an deine Observability-Plattform.

1. Das SDK installieren

Installiere die neueste Version des Claude SDK oder aktualisiere darauf:

pip install --upgrade anthropic

pip install opentelemetry-sdk

2. Einen Tracer Provider registrieren

Ein tracer provider (Tracer Provider) ist das OpenTelemetry-Objekt, das Spans erstellt und an deinen Exporter weitergibt. Das SDK verwendet den Tracer Provider, den deine Anwendung registriert, sodass deine SDK-Aufrufe unverändert bleiben. Registriere ihn vor dem ersten Aufruf, den du tracen möchtest.

Das folgende Beispiel registriert einen Tracer Provider, der jeden Span in der Konsole ausgibt, und führt dann einen Aufruf aus. Verwende es, um Spans zu sehen, bevor du eine Observability-Plattform anbindest:

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

# Registriere einen Tracer-Provider, der jeden Span auf der Konsole ausgibt.
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content)

Die Konsole zeigt einen anthropic.messages.create-Span.

3. Spans an deine Observability-Plattform senden

Ersetze den Konsolen-Exporter durch einen OTLP-Exporter, der auf deine Observability-Plattform zeigt. Für die Einrichtung in deiner Sprache siehe die OpenTelemetry-Dokumentation zu Python-Exportern, TypeScript-Exportern, .NET-Exportern, Go-Exportern, Java-SDK-Konfiguration, PHP-Exportern, oder Ruby-Exportern.

4. Das SDK konfigurieren

Verwende die folgenden Optionen, um festzulegen, was in deine Spans aufgenommen wird und wohin sie gesendet werden. Du kannst eine Option in deinem Code oder, falls vorhanden, über die unter ihrem Namen aufgeführte Umgebungsvariable festlegen.

Das folgende Beispiel zeigt, wie du jede Option verwendest:

# Verwende einen bestimmten Tracer-Provider und zeichne Inhalte auf.
# Das Setzen von open_telemetry überschreibt alle ANTHROPIC_OPEN_TELEMETRY* Umgebungsvariablen.
client = Anthropic(
    open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}}
)

# Deaktiviere Spans für einen einzelnen Client.
quiet_client = Anthropic(open_telemetry=False)

# Setze eine Konversations-ID mit with_options(), das eine Kopie des Clients zurückgibt.
# with_options() ersetzt die gesamte Option, starte also von client.open_telemetry aus.
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"}],
)

Nächste Schritte

Tracen eines Streams

Der anthropic.messages.create-Span eines Streams endet, wenn dein Code den gesamten Stream gelesen oder ihn geschlossen hat. Schließe daher einen Stream, dessen Lesen du vorzeitig beendest. Im Content-Modus enthält der Span die Modellantwort nur, wenn du den Stream mit messages.stream() liest.

Spans, die du startest, während du einen Stream liest, sind Geschwister des SDK-Spans, nicht seine Kinder. Um sie mit der Anfrage zu gruppieren, starte einen eigenen Span, der sowohl den Aufruf als auch die Leseschleife umschließt.

Tracen einer selbst gehosteten Managed-Agents-Sandbox

In einer selbst gehosteten Sandbox von Managed Agents führt deine Sandbox die Tools aus, daher stammen die Tool-Spans vom SDK statt von der API. Der Environment Worker im Python-, TypeScript- und Go-SDK erzeugt einen Span für jedes Tool, das er ausführt, und für jede Anfrage, die er sendet. Er gruppiert sie unter einem anthropic.environment.work-Span für jedes Arbeitselement.

So erhältst du diese Spans:

1. Richte in dem Prozess, der den Worker ausführt, das SDK-Tracing ein, wie in den Schritten 1 bis 4 beschrieben.
2. Erlaube Netzwerkverkehr von der Sandbox zu deiner Observability-Plattform oder deinem OpenTelemetry Collector.

Wenn der Worker ein Tool-Ergebnis sendet, ist der API-Span dieser Anfrage unter ihrem SDK-Span verschachtelt. Für Anfragen, die der Worker an Claude Platform on AWS sendet, befinden sich die API-Spans stattdessen in eigenen Traces.

Trace-Kontext und Baggage

Mit jeder Anfrage sendet das SDK den Trace-Kontext über den Propagator deiner Anwendung an die API, in Headern wie traceparent. Wenn dieser Propagator auch Baggage schreibt, sendet das SDK zusätzlich dein Baggage. Um den Trace-Kontext ohne Baggage zu senden, registriere nur den W3C-Trace-Context-Propagator.

Damit das SDK diese Header nicht sendet, zum Beispiel wenn die Instrumentierung deines HTTP-Clients sie bereits sendet, schalte die Propagation des SDK ab:

client = Anthropic(open_telemetry={"propagation": False})

Während das SDK ein MCP-Tool aufruft, ist der Tool-Span des SDK der aktuelle Span. Manche MCP-Client-Bibliotheken senden den Trace-Kontext in _meta an den MCP-Server, sodass ein Server, der ihn ausliest, seine Spans unter diesem Tool-Span zu deinem Trace hinzufügen kann. Das tun das Python-Paket mcp ab Version 2.0 und das C#-Paket ModelContextProtocol. Die MCP-SDKs für TypeScript, Go, Java, Ruby und PHP tun das nicht von selbst.

Fehlerbehebung

Compatibility