Contact Us 1-800-596-4880

Configuring a Correlation ID in Connected Mode

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 in Connected Mode using one of these methods:

Configuration Precedence

When you configure a setting in more than one place, Omni Gateway uses the first value that is set, in this order of precedence:

  1. Policy: A policy applied to the API instance.

  2. Runtime Manager runtime configuration or Configuration resource: Used if no policy value is set.

  3. Built-in default: Used if none 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.

Runtime Manager Runtime Configuration and Configuration Resource Priority

To make the Configuration resource value take precedence, add the flex.mulesoft.com/resource-priority label to the Configuration resource with a value of 2 or higher:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: Configuration
metadata:
  name: <configuration-name>
  labels:
    flex.mulesoft.com/resource-priority: "2"
spec:
  # configuration values

Omni Gateway assigns these priorities:

  • Runtime Manager runtime configuration: 1

  • Configuration resource without the label, or with a label value that isn’t an integer: 0

  • Configuration resource with the label: the label value

A Configuration resource with a priority of 2 or higher overrides the Runtime Manager runtime configuration values. If you set the Configuration priority to 1, the Runtime Manager runtime configuration values take precedence.

Configure in Runtime Manager

  1. In Anypoint Platform, select Runtime Manager.

  2. Select Omni Gateways.

  3. Select your Omni Gateway.

  4. Open Runtime configuration.

  5. Open the Tracing tab.

  6. Turn on Enable Correlation ID.

  7. In Header, enter the name of the header that carries the correlation ID.

  8. 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.

  9. Click Apply changes.

Configure with a YAML Resource

Add correlationId under spec.tracing of a Configuration resource, and then apply the resource:

apiVersion: gateway.mulesoft.com/v1beta1
kind: Configuration
metadata:
  name: correlation-id
spec:
  tracing:
    correlationId:
      header: X-Correlation-Id
      generationExpression: "prefix(uuid(), 'REQ-')"

Omni Gateway applies changes without restarting. To disable the correlation ID, remove correlationId from the resource.

Correlation ID Parameters

Parameter Required or Optional Default Value Description

header

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.

generationExpression

Optional

uuid()

Expression that generates the correlation ID when the request doesn’t include the header. See Generation Expressions.

How Omni Gateway Resolves the Correlation ID

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.

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.

Invalid Configuration

  • 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.

Override the Correlation ID for an API Instance

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.