Advanced tracing for troubleshooting

Advanced Tracing mode is a specialized, time-limited diagnostic mode within the broader API Tracing framework. While standard tracing captures basic policy execution timing, Verbose Tracing provides platform engineers with deep-dive, high-fidelity diagnostic data to rapidly diagnose and resolve intermittent production failures.

Because verbose tracing generates significant telemetry data volume, it is designed strictly as a time-limited troubleshooting tool and automatically reverts to the previously saved mode upon session expiration.

In Advanced mode, policy execution telemetry is decomposed 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. Trace spans are enriched with configurable payload details, including sanitized HTTP request and response headers, policy configuration snapshots, and truncated body previews.

Because verbose tracing is a diagnostic feature meant for short-term troubleshooting, sessions run for a capped, time-limited 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. Operators can monitor live session timers or manually terminate sessions early once troubleshooting is complete.

Additionally, when an API policy rejects or blocks an incoming request (such as an invalid API key or rate-limit breach), trace generation halts immediately at the failing policy step. Error details are attached to that step's response sub-span, and downstream policy spans are omitted to conserve storage.

Configuring advanced tracing

Prerequisites

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

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. Because this mode is designed for short-term troubleshooting, select the shortest duration your troubleshooting needs. It automatically turns off after the set duration.

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

   Sub-Toggle	Default State	UI Description & Guidance
   Request and Response Headers	On	Captures inbound/outbound HTTP headers for each span. (Note: Sensitive authorization and security headers are automatically sanitized or excluded).
   Policy Configuration	On	Includes policy config per request/response phase (truncated if large).
   Request and Response Body	Off	Captures body previews for backend requests/responses (truncated). (Capped per Gateway safety limits to protect throughput).

important

At least one sub-toggle must remain checked. The Save button remains disabled if Advanced mode is selected with all sub-toggles unchecked.

6. Under Duration, use the hours and minutes dropdown selectors to specify how long verbose tracing should remain active (up to a maximum of 4 hours).

7. 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 Save button is disabled.

8. Manage or conclude the active session using one of the following methods:

   • Manual stop: Click Stop on the active blue status banner to terminate the session immediately and revert the API tracing mode to Intermediate. Note that the Stop button is hidden for read-only users holding API Management - Read APIs privilege.
   • 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 exported to OpenTelemetry backends (such as New Relic, Jaeger, or Datadog) during an active Advanced session reflect a split per-policy and split backend span structure:

[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]

Known Issue

Some spans may appear as "Missing parent" in your observability tool (for example, New Relic) instead of nested under their expected parent span. This can occur when a policy rejects a request (for example, an IP Filter deny) or a backend connection times out or fails to establish, while Intermediate or Advanced API tracing is active. This happens because a tracing span tied to a content-processing policy does not get closed when the failure occurs, so spans created under it during normal execution arrive without a valid parent. This affects trace visualization only, in both Intermediate and Advanced tracing modes, and does not impact API request processing, policy enforcement, or backend connectivity.

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. Error attributes are appended to that policy's response sub-span, and all subsequent downstream policy spans are omitted.