Contact Us 1-800-596-4880

Correlation ID Override Policy

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

Correlation ID Override Policy

Returned Status Codes

No return codes exist for this policy

Summary

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.

Configure Policy Parameters

Omni Gateway Local Mode

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

header

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.

generationExpression

Required

N/A

Expression that generates the correlation ID when the request doesn’t include the header. For example, prefix(uuid(), 'REQ-').

See Generation Expressions for the supported functions.

Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

Basic Configuration

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, prefix(uuid(), 'REQ-').

See Generation Expressions for the supported functions.

How This Policy Works

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.

When the Global Configuration Uses a Different Header

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.

Generation Expressions

A generation expression combines the following functions and string literals:

Function Description Example

uuid()

Generates a random universally unique identifier (UUID).

uuid() returns 0b7e1c9a-5d2f-4c1e-9a3b-6f8e2d4c1a7b.

timestamp()

Returns the current time in milliseconds since the Unix epoch.

timestamp() returns 1761656400000.

prefix(expr, str)

Adds str to the beginning of the value of expr.

prefix(uuid(), 'REQ-') returns REQ-0b7e1c9a-…​.

suffix(expr, str)

Adds str to the end of the value of expr.

suffix(uuid(), '-gw') returns 0b7e1c9a-…​-gw.

concat(a, b, …​)

Joins the arguments in order.

concat('gw', '-', uuid()) returns gw-0b7e1c9a-…​.

replace(str, from, to)

Replaces every from in str with to.

replace(uuid(), '-', '') returns 0b7e1c9a5d2f4c1e…​.

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.

Example Configurations

The following examples demonstrate common configuration patterns for the Correlation ID Override policy.

Generate a UUID

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()"

Add a Prefix to the Generated ID

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-')"

Add a Suffix to the Generated ID

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')"

Remove the Hyphens from a UUID

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-')"

Use a Timestamp

In the following example, requests that don’t include the x-correlation-id header receive an ID made of REQ- and the current time in milliseconds.

- policyRef:
    name: correlation-id-override-flex
  config:
    header: "x-correlation-id"
    generationExpression: "concat('REQ-', timestamp())"