The Correlation ID AI Policy adds a unique ID to each request that AI Gateway sends to your AI Models, AI Agents, and AI MCP Servers. When a request passes through several systems, the ID lets you find the matching entries in each system’s logs and trace a single request from the client to your upstream service.
Correlation ID Policy
How does the Correlation ID Policy work?
The Correlation ID Policy adds an HTTP header to every request it processes.
The header name comes from config.header_name, and the value comes from the config.generator you choose.
AI Gateway adds the header to the request that it sends to the upstream service of the AI Model, AI Agent, or AI MCP Server.
By default, AI Gateway returns the header only to the upstream service.
Set config.echo_downstream to true to also return the header in the response to the client.
The client then receives the same value that your upstream service received.
If the client request already contains a header with the same name, the policy keeps the client’s value.
The following example adds a uuid ID to every request and returns it to the client:
Use cases
|
Use case |
How the Correlation ID Policy helps |
|---|---|
| Trace a request across systems | The upstream service receives the same ID as the client, so you can find the matching log entries in each system. |
| Give clients an ID for support requests |
Set config.echo_downstream to true so the client receives the ID in the response and can quote it in a support request.
|
| Continue an ID from your own application | The policy keeps the value of a header that the client already sends, so an ID that your application or front door creates stays the same through AI Gateway. |
| Match the header name your stack expects |
Set config.header_name to the name that your upstream service or log pipeline uses, for example X-Correlation-ID.
|
| Choose the ID format |
Set config.generator to uuid, uuid#counter, or tracker. See Generators.
|
Generators
The generator determines the format of the ID.
Choose a generator with config.generator.
The default is uuid#counter.
uuid
The uuid generator creates a new hexadecimal UUID for each request.
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxuuid#counter
The uuid#counter generator creates one UUID for each worker process.
Each request then appends a counter to the UUID after a # character.
The counter increases by one for each request that worker handles, independently of the other workers.
Requests handled by different workers therefore have different UUIDs.
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx#counterBecause many requests share the same UUID, the IDs have low cardinality.
tracker
The tracker generator creates an ID from details of the connection and the request.
ip-port-pid-connection-connection_requests-timestampThe following table describes each field:
|
Field |
Description |
|---|---|
ip
|
Address of the server that accepts a request. |
port
|
Port of the server that accepts a request. |
pid
|
Process ID. |
connection
|
Connection serial number. |
connection_requests
|
Current number of requests made through a connection. |
timestamp
|
A floating-point number for the elapsed time in seconds, including milliseconds as the decimal part, from the epoch for the current time. |
Choose a generator
Use uuid when you need a different, unrelated ID for every request.
Use uuid#counter (the default) when grouping requests by worker is acceptable, because requests handled by the same worker share a UUID.
Use tracker when you want the ID to carry connection details, such as the server address, port, and connection number.
Scopes
The Correlation ID Policy supports the following scopes:
Apply the policy globally to add an ID to all traffic that passes through AI Gateway, including requests to AI Models, AI Agents, and AI MCP Servers that you didn’t attach the policy to. Attach it to a single entity to add an ID only to that entity’s requests. For details about how scopes work, see AI Policy scopes.
To limit a global policy to specific requests, add a condition to the policy.
For example, the condition http.headers.x_trace == "1" adds the ID only to requests that carry the header x-trace: 1.
Limitations
- When a client calls a tool on an AI MCP Server of type
conversion-listener, AI Gateway doesn’t add the header to the REST request that it sends to the upstream service. The server sends that request back through AI Gateway as a new request, which doesn’t carry the generated ID. Withconfig.echo_downstreamset totrue, the client still receives the header in the response. For AI Models and AI Agents, the header is added to the upstream request.
Looking for on-prem configuration? Convert the
kongctlconfiguration to a decKyamlfile and usedeck file ai2kong. See Configure Kong AI Gateway on-prem for more information.