Skip to main content
Feedback

Advanced tracing for troubleshooting

Updated 

Advanced tracing mode is a specialized, time-limited diagnostic mode within the API Tracing framework. While standard tracing captures basic policy execution timing, this mode gives platform engineers detailed diagnostic data to diagnose and resolve intermittent production failures.

Because advanced (verbose) tracing generates significant telemetry data volume, it works as a troubleshooting tool and automatically reverts to the previously saved mode upon session expiration.

In Advanced mode, the Gateway decomposes policy execution telemetry into distinct request and response sub-spans. This dual-span model exposes phase-specific timing and metadata, allowing engineers to isolate latency to inbound processing or outbound responses. The Gateway enriches trace spans with configurable payload details, including sanitized HTTP request and response headers, policy configuration snapshots, and truncated body previews.

Sessions run for a capped duration. Select the shortest duration your troubleshooting needs. Upon reaching expiration, both the runtime engine and a background scheduler automatically revert the API to the previously saved mode.

Active sessions maintain locked configuration states to ensure telemetry consistency during diagnostic windows. You can monitor live session timers or manually terminate sessions early once troubleshooting is complete.

Prerequisites

  • Access to Boomi API Management with API Management - APIs permissions to manage deployed APIs.
  • You must enable OpenTelemetry globally on the assigned API Gateway.

Configuring advanced tracing

Follow these steps to configure and run an Advanced tracing session for a deployed API:

  1. Log in to Boomi API Management.

  2. Navigate to Manage APIs > Deployed APIs.

  3. Select your deployed API and choose Settings > API Tracing.

  4. Under Tracing Mode, select Advanced. Selecting Advanced mode immediately displays an inline performance warning banner:

important

Advanced tracing is a diagnostic feature that traces API calls through the Gateway, capturing detailed spans of headers, policy configurations, requests, and responses at every point.

  1. Under Select data to capture, configure the diagnostic sub-toggles to record your desired trace data:

    Sub-ToggleDefault StateUI Description & Guidance
    Request and Response HeadersOnCaptures inbound/outbound HTTP headers for each span.
    (Note: The Gateway automatically sanitizes or excludes sensitive authorization and security headers).
    Policy ConfigurationOnIncludes policy config per request/response phase (truncated if large).
    Request and Response BodyOffCaptures body previews for backend requests/responses (truncated).
    (The Gateway caps body capture to protect throughput).
note

Keep at least one sub-toggle selected. The Save button remains disabled if Advanced mode is selected with all sub-toggles unchecked.

  1. Under Duration, use the Hours and Minutes dropdown selectors to specify how long Advanced tracing should remain active, up to 4 hours. Select the shortest duration your troubleshooting needs.

  2. Select Save to activate the session. Upon saving:

    • A notification popup confirms session activation.
    • A blue status banner appears with a live polling countdown timer (Verbose tracing active, expires in [mm:ss]).
    • All sub-toggle checkboxes and radio controls lock to prevent mid-session changes, and the interface disables the Save button.

  3. Manage or conclude the active session using either of the following methods:

    • Manual stop: Select Stop on the active blue status banner to terminate the session immediately and revert the API tracing mode to Intermediate. Read-only users with the API Management - Read APIs privilege cannot see the Stop button.
    • Automatic expiration: When the countdown reaches 00:00, both the runtime request path and a background system scheduler evaluate the expired timestamp and automatically revert the API to the previously saved mode. The banner updates to state: Verbose tracing session has expired. Tracing has been automatically reverted to Intermediate.

Observability backend trace hierarchy

Traces that the Gateway exports to OpenTelemetry backends (such as New Relic, Jaeger, or Datadog) during an active Advanced session show separate spans for each policy and for the backend:

[Root Server Span]  (span.kind=server)
  ├── [Backend Request Span]
  ├── [Policy 1 - Request Sub-Span]  (Inbound headers, truncated config)
  ├── [Policy 1 - Response Sub-Span] (Execution timing, status)
  ├── [Policy 2 - Request Sub-Span]  (Inbound headers, payload preview)
  ├── [Policy 2 - Response Sub-Span] (Error attributes if terminated)
  └── [Backend Response Span]

Trace hierarchy showing separate request and response sub-spans for each policy, with backend request and response spans

Early termination handling

If an API policy rejects or blocks a request (for example, an API key failure or rate-limit violation), trace generation halts immediately at the rejecting policy step. The Gateway appends error attributes to that policy's response sub-span and omits all later downstream policy spans.

On this Page