D5 · Context & Reliability › Cluster 8 · Observability & Production Ops

8.2 · Logging & Tracing (Request IDs)

Make failures debuggable

CONCEPT Capture the request-id on every call

When a request behaves oddly and you open a support ticket, the first thing Anthropic asks for is the request ID. Every API response carries a unique request-id response header (a value like req_018EeWyXxfu5pfWkrYcMdjWG), and the same identifier appears as the request_id field inside error response bodies. Log it on both success and failure — you can't retrieve it after the fact.

SurfaceWhere the ID livesHow to read it
Successful responserequest-id headerPython/TS: message._request_id; others: raw-response accessor
Error bodyrequest_id JSON fieldOn the parsed error object
Raw headers (any SDK)request-id.with_raw_response → headers.get("request-id")
🔑 The _request_id property on Python/TS response objects is public despite the underscore. Include it in every log line so a customer complaint maps to one exact call.

CONCEPT Log I/O + latency + tokens, propagate a trace ID

A useful log record is more than the request ID. For each call capture the inputs (model, prompt/params — redacted as policy requires), the outputs (text, stop_reason), the latency, and the token usage (8.1). For agents, a single user task fans out into many API calls and tool invocations — so mint one trace ID at the top of the task and propagate it across every model call and tool call. That's what lets you reconstruct "what did the agent do" as a single timeline instead of disconnected log lines.

Correlate two IDs: your own trace ID (spans the whole agent run, your invention) and Anthropic's request-id (one per API call, for support). The trace ID answers "what happened"; the request-id answers "which exact call, and can Anthropic see it too."

DIAGRAM One trace ID across an agent's tool calls

flowchart TD U["User task"] --> T["Mint trace_id
(one per run)"] T --> C1["API call 1
trace_id + request-id A"] C1 --> TOOL["Tool call
trace_id propagated"] TOOL --> C2["API call 2
trace_id + request-id B"] C2 --> DONE["Final answer"] C2 -.->|"error?"| ERR["🔴 Log request_id
from error body"] C1 --> LOG["📋 One correlated timeline:
inputs · outputs · latency · tokens"] C2 --> LOG ERR --> LOG classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class DONE ok; class LOG gate; class ERR bad;

CODE A correlated log record per call

Read the request ID from the response, and from the error body when a call throws. One trace_id threads the whole run.

import time, uuid, anthropic

trace_id = uuid.uuid4().hex  # mint ONCE at the top of the agent task

def call(client, **params):
    t0 = time.monotonic()
    try:
        resp = client.messages.create(**params)
        log({
            "trace_id": trace_id,
            "request_id": resp._request_id,          # from the request-id header
            "latency_ms": (time.monotonic() - t0) * 1000,
            "input": params["messages"], "stop_reason": resp.stop_reason,
            "usage": resp.usage.to_dict(),           # tokens (8.1)
        })
        return resp
    except anthropic.APIStatusError as e:
        log({"trace_id": trace_id,
             "request_id": e.request_id,           # same id, from the error body
             "status": e.status_code, "error_type": e.type,
             "latency_ms": (time.monotonic() - t0) * 1000})
        raise

TRADE-OFFS What to put in the log

✅ Structured, ID-rich records

  • request-id → Anthropic can trace it end-to-end
  • trace-id → whole agent run reconstructs as one timeline
  • Redact PII in prompts; keep IDs, latency, tokens

⚠️ Prose logs / no IDs

  • Cheap to write, human-readable at a glance
  • But: support can't locate the call without a request-id
  • Agent runs can't be stitched back together

EXAM TRAPS

Trap: Only capturing the request ID on success. → The same request_id is on the error body too — and that's exactly the call you'll need to report. Log it on failure.
Trap: Thinking _request_id is private because of the underscore. → It's a documented, public property on Python/TS response objects. Other SDKs read the request-id header via the raw-response accessor.
Trap: Using the Anthropic request-id to correlate an agent's whole run. → One request-id = one API call. To span a multi-call agent run you need your own trace ID, minted once and propagated across tool calls.
Trap: Logging full prompts with user PII and no redaction. → Logs are a distribution surface. Redact sensitive input; keep the load-bearing metadata (IDs, latency, tokens, stop_reason).

PRACTICE

Q1 · A customer reports a bad response. What's the one field you need to have logged?

The request-id (from the request-id response header, exposed as _request_id in Python/TS). It lets Anthropic support trace that exact request end-to-end. Without it, there's no reliable way to locate the call.

Q2 · How do you correlate the 6 API calls an agent made for one user task?

Mint one trace ID at the start of the task and propagate it through every model call and tool call, logging it on each record. Anthropic's request-id is per-call and can't span the run; your trace ID stitches the timeline together.

Q3 · Where do you get the request ID when a call raises an error?

From the error response body — it carries a request_id field (surfaced on the SDK's typed exception, e.g. e.request_id). Same identifier as the success-path request-id header.