How to Propagate X-Request-ID in Python

Generate a unique request ID when one is missing and pass it through API calls for distributed tracing.

Easy Python 3.10+ Aug 9, 2026 API design & gRPC 12 views 0 copies

Python code

27 lines
Python 3.10+
import uuid


def generate_request_id() -> str:
    """Generate a unique request ID similar to X-Request-ID header."""
    return str(uuid.uuid4())


def propagate_request_id(request_id: str | None) -> str:
    """Return the request ID for propagation, generating one if missing."""
    if request_id:
        return request_id
    return generate_request_id()


if __name__ == "__main__":
    # Simulate an incoming request without an X-Request-ID
    incoming = None
    propagated = propagate_request_id(incoming)
    print(f"Incoming X-Request-ID: {incoming}")
    print(f"Propagated X-Request-ID: {propagated}")

    # Simulate an incoming request that already has an X-Request-ID
    incoming_with_id = "7f9c1b2a-3d4e-4f5a-9b8c-1d2e3f4a5b6c"
    propagated_with_id = propagate_request_id(incoming_with_id)
    print(f"\nIncoming X-Request-ID: {incoming_with_id}")
    print(f"Propagated X-Request-ID: {propagated_with_id}")

Output

stdout
Incoming X-Request-ID: None
Propagated X-Request-ID: 7a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d

Incoming X-Request-ID: 7f9c1b2a-3d4e-4f5a-9b8c-1d2e3f4a5b6c
Propagated X-Request-ID: 7f9c1b2a-3d4e-4f5a-9b8c-1d2e3f4a5b6c

How it works

generate_request_id() uses uuid.uuid4() to produce a collision-resistant, RFC 4122-compliant ID. The propagate_request_id() function reuses any existing header value instead of generating a new one, preserving the trace across service hops. The | None type hint and string check handle both empty strings and missing headers gracefully. This pattern is the standard way to maintain a request trace ID across distributed systems.

Common mistakes

  • Generating a new ID even when the incoming request already has one
  • Returning an empty string instead of generating a fresh ID when the header is blank
  • Using uuid1() which leaks MAC address and timestamp information

Variations

  1. Use `secrets.token_hex(16)` for a shorter, URL-safe ID
  2. Wrap the helper in a middleware class to automatically attach the header to every outbound request

Real-world use cases

  • Forwarding the X-Request-ID header to downstream microservices for end-to-end log correlation.
  • Attaching a correlation ID to every log line in a serverless function for easier debugging.
  • Injecting the request ID into outbound HTTP calls so third-party APIs can trace failures back to you.

Sponsored

Run this sample

Open the browser IDE to tweak the example and see results without installing anything.

Open editor

More from API design & gRPC

Related tutorials and quizzes for this topic.