ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-142] X-Request-Id ​

Overview ​

This document establishes guidelines for using the X-Request-Id header in our system to track requests between clients and servers. The use of X-Request-Id aims to improve traceability, enhance debugging processes, and ensure consistent tracking of requests in distributed services and microservices.

Guidance ​

Definition ​

X-Request-Id is an HTTP header used to carry a unique identifier for each request. Although not a standard, it is a widely adopted convention. This identifier allows tracking and associating logs across different services and systems that handle the request.

Requirements ​

  • Clients SHOULD generate a unique X-Request-Id for each outgoing request.
    • If the client does not generate an X-Request-Id, the first server receiving the request SHOULD generate a unique X-Request-Id and include it in the response and any subsequent requests.
  • Any service receiving a request with X-Request-Id (including microservices) SHOULD propagate this header with the same value to any downstream services or components involved in processing the request.
    • Once an X-Request-Id is set for a specific request flow, it must not be changed.
  • All services (including microservices) SHOULD include X-Request-Id in their logs. This allows associating logs across different services, making it easier to trace the entire lifecycle of a request.
    • Monitoring and alerting systems should be configured to use X-Request-Id for tracking and debugging.
  • X-Request-Id SHOULD be a UUID (Universally Unique Identifier) to ensure the uniqueness of all requests.
    • For example: X-Request-Id: 123e4567-e89b-12d3-a456-426614174000

Implementation Considerations ​

  • Ensure that load balancers and API Gateways are configured to retain the X-Request-Id header.

Design Considerations ​

There are some alternative custom headers, such as X-Flow-Id and X-Correlation-Id, but they are less common, so we do not consider them here. See usage statistics:

References ​