Getting started Community Training Tutorials Documentation APIs, AI & Tools
- policyRef:
name: correlation-id-override-flex
config:
header: <string> // REQUIRED
generationExpression: <string> // REQUIRED
Policy Name |
Correlation ID Override |
Summary |
Overrides the global correlation ID header and generation expression for an API |
Category |
Troubleshooting |
First Omni Gateway version available |
v1.15.0 |
Release Notes |
|
Returned Status Codes |
No return codes exist for this policy |
The Correlation ID Override policy replaces the global correlation ID header and generation expression for an API. A correlation ID is a value that identifies a request across Omni Gateway, your upstream services, and your tracing backend. Use this policy to change the name of the header that carries the correlation ID and how Omni Gateway generates the ID when a request doesn’t include one.
Use this policy when an API needs correlation IDs that differ from the global settings. For example, you can:
Generate a unique ID for each request with uuid(), so you can follow a single request through your logs.
Add a prefix with prefix(uuid(), 'REQ-'), so you can tell which API or application created the ID.
Add a suffix with suffix(uuid(), '-gw'), so you can tell that Omni Gateway created the ID.
Add a timestamp with timestamp(), so you can see when the ID was generated.
Combine values with concat(a, b, …), or change text with replace(str, from, to), to match the ID format that your other systems expect.
See Generation Expressions for the full list of functions.
When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:
- policyRef:
name: correlation-id-override-flex
config:
header: <string> // REQUIRED
generationExpression: <string> // REQUIRED
| Parameter | Required or Optional | Default Value | Description |
|---|---|---|---|
|
Required |
N/A |
Name of the request header that carries the correlation ID. If the request doesn’t include this header, Omni Gateway generates a correlation ID and adds the header to the request. |
|
Required |
N/A |
Expression that generates the correlation ID when the request doesn’t include the header. For example, See Generation Expressions for the supported functions. |
When you apply the policy from the UI, the following parameters are displayed:
| Element | Required | Description |
|---|---|---|
Header |
Yes |
Name of the request header that carries the correlation ID. If the request doesn’t include this header, Omni Gateway generates a correlation ID and adds the header to the request. |
Generation expression |
Yes |
Expression that generates the correlation ID when the request doesn’t include the header. For example, See Generation Expressions for the supported functions. |
The Correlation ID Override policy replaces the global correlation ID configuration for an API. The policy doesn’t merge with the global configuration. The API uses only the header and generation expression that you set in the policy, and other APIs keep using the global configuration. If no global correlation ID is configured, the policy enables the correlation ID for that API only.
For each request, Omni Gateway resolves the correlation ID as follows:
| Request | Correlation ID |
|---|---|
Includes the header |
The value the client sent. Omni Gateway doesn’t apply the generation expression. |
Doesn’t include the header |
A new value generated by the generation expression, different for each request. Omni Gateway adds the header to the request. |
Includes the header with an empty value |
Omni Gateway treats the header as missing and generates a value. |
Includes the header more than once |
The first value. Omni Gateway forwards all values as received. |
The header name isn’t case-sensitive. Omni Gateway never removes a header that the client sends.
For every request, Omni Gateway then:
Forwards the header with the correlation ID to the upstream service.
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 the request when tracing is enabled and the request is sampled, so you can search traces by correlation ID.
If the global configuration and the policy use different headers, the API uses only the policy header. For example, the global configuration uses X-Correlation-Id and the policy uses X-Api-Correlation-Id:
If the request includes neither header, the upstream service receives X-Api-Correlation-Id with a generated value. Omni Gateway doesn’t add X-Correlation-Id.
If the request includes X-Api-Correlation-Id, the upstream service receives it unchanged, and the value is the correlation ID.
If the request includes only X-Correlation-Id, Omni Gateway forwards it unchanged as an ordinary header and adds X-Api-Correlation-Id with a generated value. The generated value is 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.
The following examples demonstrate common configuration patterns for the Correlation ID Override policy.
In the following example, requests that don’t include the x-correlation-id header receive a generated UUID.
- policyRef:
name: correlation-id-override-flex
config:
header: "x-correlation-id"
generationExpression: "uuid()"
In the following example, requests that don’t include the x-request-id header receive a generated UUID that begins with REQ-.
- policyRef:
name: correlation-id-override-flex
config:
header: "x-request-id"
generationExpression: "prefix(uuid(), 'REQ-')"
In the following example, requests that don’t include the x-correlation-id header receive a generated UUID that ends with -gw.
- policyRef:
name: correlation-id-override-flex
config:
header: "x-correlation-id"
generationExpression: "suffix(uuid(), '-gw')"
In the following example, requests that don’t include the x-request-id header receive a generated UUID without hyphens, with REQ- at the beginning.
- policyRef:
name: correlation-id-override-flex
config:
header: "x-request-id"
generationExpression: "prefix(replace(uuid(), '-', ''), 'REQ-')"