Correlation ID header override and passthrough behavior

The Correlation ID plugin generates a unique UUID for each request and adds it to the request headers as Kong-Request-Id. To use a custom correlation ID instead, include the Kong-Request-Id header in your request. The plugin passes the provided value through unchanged.

For example, if a Service and Route have the Correlation ID plugin enabled, a request to the Route returns a generated UUID in the response headers:

Kong-Request-ID: <SOME UNIQUE UUID VALUE>

To pass a specific correlation ID, include the Kong-Request-Id header with your chosen value:

curl http://localhost:18000/test123 -H "Kong-Request-Id: ab58c8d9-04d2-4b6e-9f31-431cf922ab8d"

The response contains the Kong-Request-Id value you provided:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "Kong-Request-Id": "ab58c8d9-04d2-4b6e-9f31-431cf922ab8d",
    "User-Agent": "curl/7.81.0",
    "X-Amzn-Trace-Id": "Root=1-63f5227e-44d396634930aeed239e4407",
    "X-Forwarded-Host": "localhost",
    "X-Forwarded-Path": "/test123",
    "X-Forwarded-Prefix": "/test123"
  },
  "json": null,
  "method": "GET",
  "origin": "172.20.0.1, 64.57.201.84",
  "url": "http://localhost/anything"
}

This behavior lets you propagate an existing trace ID from an upstream system into Kong Gateway, which is useful for end-to-end request tracing across services.