Getting started Community Training Tutorials Documentation APIs, AI & Tools
header
A correlation ID is a value that identifies a request across Omni Gateway, your upstream services, and your tracing backend. When you configure a correlation ID, Omni Gateway makes sure that every request has one:
If the request includes a correlation ID header, Omni Gateway keeps its value.
If the request doesn’t include a correlation ID header, Omni Gateway generates a value with a generation expression and adds the header to the request.
For every request, Omni Gateway also:
Adds a correlation.id member to the W3C baggage header, so OpenTelemetry-instrumented services downstream receive the correlation ID. Omni Gateway keeps the other members of the baggage header, and replaces an existing correlation.id member.
Adds a correlation.id attribute to the spans of traced requests, so you can search traces by correlation ID.
The correlation ID applies to every API instance in the gateway. To use a different header or generation expression for one API instance, apply the Correlation ID Override Policy.
Configure a correlation ID for Managed Omni Gateway using one of these methods:
Runtime Manager runtime configurations: Applies to all API instances in the gateway.
Policy: Applies to one API instance and provides granular control.
When you configure a setting in more than one place, Omni Gateway uses the first value that is set, in this order of precedence:
Policy: A policy applied to the API instance.
Runtime Manager runtime configuration: Used if no policy value is set.
Built-in default: Used if neither of the other values is set. A policy value overrides the gateway-level value for the API instance it’s applied to. API instances without the policy use the gateway-level value.
In Anypoint Platform, select Runtime Manager.
Select Omni Gateways.
Select your Omni Gateway.
Open Runtime configuration.
Open the Tracing tab.
Turn on Enable Correlation ID.
In Header, enter the name of the header that carries the correlation ID.
In Generation Expression, enter the expression that generates the correlation ID when the request doesn’t include the header. For example, prefix(uuid(), 'REQ-').
In Runtime Manager, Header and Generation Expression are both required.
Click Apply changes.
| Parameter | Required or Optional | Default Value | Description |
|---|---|---|---|
|
Required |
N/A |
Name of the request header that carries the correlation ID. When the header isn’t present, Omni Gateway adds it. The name isn’t case-sensitive. |
|
Optional |
|
Expression that generates the correlation ID when the request doesn’t include the header. See Generation Expressions. |
For each request, Omni Gateway resolves the correlation ID as follows:
Request includes the header: The correlation ID is the value the client sent. Omni Gateway doesn’t apply the generation expression.
Request doesn’t include the header: The correlation ID is a new value generated by the generation expression, different for each request. Omni Gateway adds the header to the request.
Request includes the header with an empty value: Omni Gateway treats the header as missing and generates a value.
Request includes the header more than once: The correlation ID is the first value. Omni Gateway forwards all values as received.
Omni Gateway never removes a header that the client sends.
For example, a request with the header baggage: userId=1,correlation.id=stale and the correlation ID REQ-1234 reaches the upstream service with the header baggage: userId=1,correlation.id=REQ-1234.
If you defined a tracing label named correlation.id, Omni Gateway ignores that label and logs a warning. The correlation.id span attribute always contains the correlation ID.
A generation expression combines the following functions and string literals:
| Function | Description | Example |
|---|---|---|
|
Generates a random universally unique identifier (UUID). |
|
|
Returns the current time in milliseconds since the Unix epoch. |
|
|
Adds |
|
|
Adds |
|
|
Joins the arguments in order. |
|
|
Replaces every |
|
Use single or double quotes for string literals, for example 'REQ-' or "REQ-". You can nest functions. For example, prefix(replace(uuid(), '-', ''), 'REQ-') generates REQ- followed by 32 hexadecimal characters.
An expression can be nested at most 32 levels deep, and can’t generate a value longer than 8192 bytes.
If the header isn’t a valid header name, for example X Correlation with a space, Omni Gateway doesn’t apply the correlation ID and logs an error. The rest of the configuration and the traffic aren’t affected.
If the generation expression isn’t valid, for example it uses an unknown function, has the wrong arguments, or exceeds the limits, Omni Gateway rejects the configuration update. Omni Gateway doesn’t apply this update or any later update until you fix the expression. Check the expression before you apply it.
To use a different header or generation expression for one API instance, apply the Correlation ID Override Policy policy to the API instance. The policy replaces the correlation ID configuration of the gateway for that API instance. Other API instances keep the configuration of the gateway.