Track Request IDs

A Single Identifier for Each Request

Lesson 147 used the request ID as one of the fields in a log line. This lesson looks at it more closely, because it is the most useful identifier in the whole reliability toolkit. Every HTTP request sent to the service carries a unique request ID, returned in a request-id header on the response, and exposed by the SDK on errors and responses. When something goes wrong, the request ID is the thread that connects the application's record of the failure to the service's own record of the request.

Two things make request IDs easy to misuse. First, a single user action can involve several requests, because retries create new ones. Second, the request ID is not the same as the ID of the message the service returns. This lesson explains the difference, shows how to keep every attempt linked to one operation, and builds a trace that can be handed to a support team in one piece.

Request IDs and Message IDs

The service issues two kinds of identifier that look similar, and they answer different questions:

A failed request has a request ID but no message ID, because no message was created. A successful request has both. The request ID is always the right thing to quote when reporting a problem, because it exists even when the answer does not.

The request ID appears in two places. On errors, the SDK exposes it as request_id, as Lesson 141 showed. On successful responses, the same value is available from the response wrapper, and Lesson 49 showed how to read it. A program should record it on every call, whether the call succeeded or failed, because successes are sometimes the subject of a complaint too.

Each Attempt Has Its Own Request ID

Retries complicate tracing. When a request fails and is retried, the retry is a new HTTP request, and it gets its own request ID. A single logical operation may therefore produce several request IDs, one per attempt:

operation: summarize-report-42
  attempt 1  req_a1f  → 529 overloaded
  attempt 2  req_b7c  → 429 rate limited
  attempt 3  req_c90  → success, message msg_xyz

If a support team receives only the last request ID, they see the success and miss the two failures that came before it. If they receive only the first, they see the overload and miss the recovery. The complete picture needs every attempt, so the trace must record all of them, not only the one that ended the operation.

A Trace for One Operation

A trace is a record that groups every attempt under one operation identifier. The operation has its own ID, chosen by the application, and each attempt adds a row with its request ID, its number, and its outcome. The record can be written to a log, stored in a database, or attached to a ticket:

"""request_trace.py: group every attempt of one operation under one trace."""

from dataclasses import dataclass, field


@dataclass
class Attempt:
    number: int
    request_id: str | None
    outcome: str


@dataclass
class Trace:
    trace_id: str
    operation: str
    attempts: list[Attempt] = field(default_factory=list)

    def record(self, request_id: str | None, outcome: str) -> None:
        self.attempts.append(Attempt(len(self.attempts) + 1, request_id, outcome))

    def support_summary(self) -> str:
        lines = [f"trace {self.trace_id} ({self.operation})"]
        for attempt in self.attempts:
            lines.append(f"  attempt {attempt.number}: request_id={attempt.request_id} {attempt.outcome}")
        return "\n".join(lines)

How It Works

1. The trace ID belongs to the application. It identifies the user action or job, and it stays the same across every attempt, so all attempts can be found together in logs.
2. Each attempt is recorded in order, with its number, its request ID, and its outcome. The request ID may be absent when a connection never produced one, which is why the field can be None.
3. support_summary() produces a text block that can be pasted into a support ticket, containing every request ID in sequence.
4. The trace does not depend on the success or failure of the operation. It records what was tried, which is what an investigation needs.

Connecting Application Traces to Service Requests

The application's trace and the service's request IDs live in different systems, and they must be linked. The link is made when each attempt is recorded: the trace stores the service's request ID alongside the application's own identifiers. Searching the application's logs by trace ID then finds every attempt, and searching the service's records by request ID finds the exact request.

Many applications already have a request or correlation ID from their own web framework. Reusing that identifier as the trace ID connects the service's request to the user's HTTP request, so the whole path from the browser to the model can be followed in one search.

Practical Example: A Job With Three Attempts

The example below runs an operation that fails twice and then succeeds. The fake service returns a request ID on every response, including the failures, and the trace records each one. The printed summary is what a support engineer would receive.

"""trace_demo.py: a retried operation, traced from first attempt to success."""

from request_trace import Trace

FAKE_RESPONSES = [
    ("req_a1f", "error 529 overloaded"),
    ("req_b7c", "error 429 rate limited"),
    ("req_c90", "success, message msg_xyz"),
]

if __name__ == "__main__":
    trace = Trace(trace_id="job-7781", operation="summarize-report-42")
    for request_id, outcome in FAKE_RESPONSES:
        trace.record(request_id, outcome)
    print(trace.support_summary())

Output:

trace job-7781 (summarize-report-42)
  attempt 1: request_id=req_a1f error 529 overloaded
  attempt 2: request_id=req_b7c error 429 rate limited
  attempt 3: request_id=req_c90 success, message msg_xyz

How It Works

1. The trace is created once, with the application's job identifier and a description of the operation.
2. Each response is recorded as it arrives, including the two failures, which carry request IDs just as the success does.
3. The summary lists every attempt in order, so the support engineer can search the service's records for req_a1f, req_b7c, or req_c90, and see the whole sequence.
4. The successful message ID is recorded in the outcome text, which lets the answer itself be found later, separately from the request that produced it.

Keeping Request IDs Where They Are Needed

A request ID is only useful if it survives long enough to be used. Three places commonly lose it. Exception handlers that log only the message discard the attribute. Retry layers that wrap the call in a new exception can hide the original. And background jobs that write only the final status lose the attempts entirely. Each of these is fixed by carrying the trace object through the whole operation, and writing the attempt record at the moment each response or error arrives.

Summary

Every request has its own request ID, and a retried operation has several. A trace groups them under one operation identifier, so the full sequence can be handed to someone who needs it. Request IDs differ from message IDs, and a failed request has only the first. The application's trace identifier and the service's request IDs together let a single search follow an operation from the user's action to the model's record. The next lesson turns to a different kind of list: paginated results, where many items arrive in pages.