Correlation ID Policy

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.

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-xxxxxxxxxxxx

uuid#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#counter

Because 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-timestamp

The 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. With config.echo_downstream set to true, 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 kongctl configuration to a decK yaml file and use deck file ai2kong. See Configure Kong AI Gateway on-prem for more information.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!