Configuring and Exporting Distributed Tracing for Managed Omni Gateway

OpenTelemetry provides a unified standard for instrumenting, generating, collecting, and exporting telemetry data across distributed systems. Omni Gateway supports OpenTelemetry, enabling you to configure the generation of distributed tracing data for all API traffic managed by the gateway. This integration delivers deep visibility into API request flows, making it easier to analyze system behavior, troubleshoot issues, and understand interactions between Omni Gateway APIs and external services.

Tracing enables you to track Omni Gateway API interactions. When multiple systems and services are involved, distributed tracing tracks API requests as they flow through distributed environments, providing a comprehensive view of the API’s execution.

You can export Omni Gateway trace data to third-party observability and analytics platforms, such as New Relic, Azure Monitor, Splunk, or any OpenTelemetry-compliant tool. Omni Gateway can send traces directly to an OpenTelemetry endpoint, or, for gateways connected to Anypoint Platform, send traces to Anypoint Monitoring, where the Anypoint Monitoring Telemetry Exporter forwards them to third-party providers. Exporting traces enables end-to-end observability, so you can correlate API traces with data from other systems to build a comprehensive view of your environment.

Configure distributed tracing for Managed Omni Gateway using one of these methods:

Managed Omni Gateway deployment: Set initial distributed tracing values when you create the gateway.
Runtime Manager runtime configurations: Applies to all API instances in the gateway after the gateway is deployed.
Policy: Applies to one API instance and provides granular control.

Export traces from Managed Omni Gateway using one of these methods:

OpenTelemetry provider: Managed Omni Gateway sends traces directly to your OpenTelemetry collector by using the OpenTelemetry Protocol (OTLP) over HTTP or gRPC. Traces don’t pass through Anypoint Monitoring. Configure the endpoint, authentication headers, and resource attributes in the Runtime Manager tracing configuration.
Anypoint Monitoring Telemetry Exporter: Managed Omni Gateway sends traces to Anypoint Monitoring, and the Telemetry Exporter forwards them to third-party providers. Use this method to view traces in Anypoint Monitoring and in a third-party tool.

You can export traces and logs to the same service. Traces and logs are configured separately, so to export both, configure trace export on the Tracing tab and log export on the Logging tab. See Configuring and Exporting Logs for Managed Omni Gateway.

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:

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.

Before You Begin

To use the OpenTelemetry with Omni Gateway, you must be familiar with:

Distributed tracing concepts, including traces and spans.

If you’re new to distributed tracing and OpenTelemetry, we recommend starting with What is OpenTelemetry and Understanding distributed tracing.

Configure Distributed Tracing During Managed Gateway Deployment

Set distributed tracing values in the deployment flow when you create a Managed Omni Gateway. For the UI steps and parameter descriptions, see Deploy a Managed Omni Gateway.

Configure and Export Distributed Tracing in Runtime Manager

Send traces to Anypoint Monitoring, or send them directly to a third-party observability service, such as New Relic, Splunk, or any OpenTelemetry-compliant tool, by using the OpenTelemetry Protocol (OTLP).

In Anypoint Platform, select Runtime Manager.
Select Omni Gateways.
Select your Omni Gateway.
Open Runtime Configurations.
Open Tracing.
Turn on Enable Tracing.
Under Provider, for Type, select where to send traces:
- To send traces to Anypoint Monitoring, select Anypoint Monitoring.
- To send traces directly to an OpenTelemetry endpoint, select OpenTelemetry, and then under Properties, configure the OpenTelemetry provider. See OpenTelemetry Provider Parameters.
Under Sampling, set the Overall, Client, and Random sampling percentages. See Sampling Parameters.

To configure sampling only on a per-API basis with the Tracing policy, set Overall to 0.
Optionally, under Labels, click Add to add span attributes to traces. See Label Parameters.
Click Apply changes.

OpenTelemetry Provider Parameters

Parameter Required Description

Parameter	Required	Description
Service Type	Yes	Protocol used to send traces to the OpenTelemetry collector. Supported values are HTTP and gRPC.
Address	Yes	Address of the OpenTelemetry collector. For HTTP, include the traces path, for example, `https://otel-collector.example.com:4318/v1/traces`.
Service Name	Yes	Service name reported in exported traces, for example, `my-managed-gateway`.
Timeout (seconds)	Yes	Connection timeout, in seconds. The default value is `10`.
Headers	No	Custom headers to add to requests sent to the OpenTelemetry endpoint, such as an API key for authentication. Click Add to add a header name and value.
Resource Attributes	No	Custom resource attributes to add to reported traces, such as `deployment.environment`. Click Add to add an attribute name and value.

Service Type

Yes

Protocol used to send traces to the OpenTelemetry collector. Supported values are HTTP and gRPC.

Address

Yes

Address of the OpenTelemetry collector. For HTTP, include the traces path, for example, https://otel-collector.example.com:4318/v1/traces.

Service Name

Yes

Service name reported in exported traces, for example, my-managed-gateway.

Timeout (seconds)

Yes

Connection timeout, in seconds. The default value is 10.

Headers

Custom headers to add to requests sent to the OpenTelemetry endpoint, such as an API key for authentication. Click Add to add a header name and value.

Resource Attributes

Custom resource attributes to add to reported traces, such as deployment.environment. Click Add to add an attribute name and value.

Sampling Parameters

Parameter Default Value Description

Parameter	Default Value	Description
Overall	100	Target percentage of requests that are traced after all other sampling checks are applied, such as client-directed, force tracing, and random sampling.
Client	100	Target percentage of requests that are force traced if the `x-client-trace-id` header is set.
Random	100	Target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.

Overall

100

Target percentage of requests that are traced after all other sampling checks are applied, such as client-directed, force tracing, and random sampling.

Client

100

Target percentage of requests that are force traced if the x-client-trace-id header is set.

Random

100

Target percentage of requests that are randomly selected for trace generation, if not requested by the client or not forced.

Label Parameters

Labels add span attributes to the trace data for all API instances in the gateway.

Parameter Description

Parameter	Description
Name	Name of the label, used as a span attribute name.
Type	Where the value for the label is taken from. Supported values are `literal`, `environment`, and `requestHeader`.
Key Name	Key used to retrieve the value, such as an environment variable or request header name.
Default Value	Value to use if the key isn’t found or the retrieved value is empty.

Name

Name of the label, used as a span attribute name.

Type

Where the value for the label is taken from. Supported values are literal, environment, and requestHeader.

Key Name

Key used to retrieve the value, such as an environment variable or request header name.

Default Value

Value to use if the key isn’t found or the retrieved value is empty.

Configure Distributed Tracing for Specific APIs

To override the globally configured distributed tracing settings for specific APIs, apply the Tracing policy. First enable and configure distributed tracing for the gateway, then apply this policy to the APIs to instrument:

Tracing Policy

Export Traces from Anypoint Monitoring to Third Parties

To export traces to third-party providers using the Anypoint Monitoring Telemetry Exporter, see Exporting Telemetry Data to Third-Party Monitoring Systems.