Trace overview

Apigee hybrid lets you collect trace data, which shows the entire request/response flow of your API proxies. This includes all request/response parameters along with transformations applied to them at policy execution time. This is important during proxy development and deployment for debugging and troubleshooting.

Trace architecture

The following image shows the process of creating a new debug session:

A high-level
  view of a request to start a debug session

Because of the asynchronous nature of multiple pollings, hybrid trace data is not available in real time. Instead, there is a slight delay in the availability of trace data as compared to using trace with Apigee Edge for the Cloud.

Trace data is persisted in the management plane for up to 24 hours.

Use trace

This section provides a high level overview of how to use trace with hybrid. Subsequent sections provide more detail.


Before you can use trace, you must be sure that the following are configured:

Service accounts:

  • apigee-synchronizer (role: Apigee Synchronizer Manager)
  • apigee-udca (role: Apigee Analytics Agent)

For more information, see Create service accounts.


When does a debug session end?

When you create a debug session, two properties determine when it ends:

  • timeout: The length of time that a session collects data for. The default is 300 seconds (or 5 minutes). The maximum value is 600 seconds (or 10 minutes).
  • count: The maximum number of requests that are recorded in a single session per Message Processor. Because the number of Message Processors in most clusters is variable, the effects of the count can be unpredictable. Apigee does not recommend customizing this setting.

When one of these is reached, the debug session for that Message Processor ends.

This section uses the following terms to refer to debug sessions:

  • active session refers to a debug session that is still has not yet reached its timeout or exceeded its count. An active session is still recording request data for requests that are not filtered out.
  • completed session is a debug session that has either reached its count or timeout; a completed session no longer records data about new requests and its data will be deleted within 24 hours of the time at which the session ended.

You cannot configure a debug session's timeout in the hybrid UI. You can configure timeout with the trace APIs when you create a new debug session.

Use trace with the hybrid UI

The following sections describe how to use trace with the hybrid UI:

Use the trace APIs

The trace APIs section describes how to use the following APIs:

Differences between Edge and hybrid trace

The following table summarizes the differences between trace in Apigee hybrid and Apigee Edge:

Feature Apigee Edge Cloud Apigee hybrid
Timeliness Real time; synchronous Slight delay; asynchronous
Session name/ID Accepts session name from the user Doesn’t accept session name from the user
Filters Basic filter support, such as header and query parameter filtering Support for complex filtering logic, including both AND and OR logical operations. Access to any flow variable mentioned in the Flow variables reference. Syntax is the same as used with conditionals, as shown in the Conditions reference.
Session timeout

Defines the length of the debug session as well as how long data is retained.

Default value is 20 minutes when initiated via API calls and 10 minutes when initiated in the UI.

Defines only the length of the debug session. The starting point is when the Message Processor receives the request to run in debug mode.

Default value is 5 minutes if the session was initiated with the API and 10 minutes if it was initiated in the UI.

Data is persisted for 24 hours before hybrid automatically deletes it.

Data masking

(Data masking in hybrid does not work as intended due to a defect. As a workaround, you can delete trace data as it becomes available with the trace APIs or the hybrid UI.)
Session validity

Length of time in which the session creation request is valid. If the debug session does not start within this amount of time, the Synchronizers can disregard the session creation request. Be sure to keep your Synchronizers' clocks in synch, as described in Prerequisites.
Trace request count Maximum of 20 per Message Processor Default is 10 per Message Processor; maximum is 15.
API Apigee Edge Cloud Apigee hybrid
Apigee hybrid exposes the Debug Sessions API and Debug Session Data API, but does not support the following via the Apigee APIs:
Stop debug session

Delete specific transactions


When you create a new debug session, you can add a filter to that session so that hybrid returns only the data you want. A filter is a conditional statement that hybrid evaluates against request and response messages to determine if its trace data should be included in the debug session.

Filter syntax

Filters support the same syntax that is used by Edge conditions, as described in Conditions reference. This includes:

In addition, filters can access all flow variable that are described in the Flow variables reference as well as custom variables. The following examples show just some of the possible flow variables that you can use in filters:

# Response codes:
  response.status.code <= 599
  response.status.code >=301 &amp;&amp; response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') &amp;&amp; request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed' == 'IPDeniedAccess'

For information about using custom variables, see How to use custom attributes in Apigee Edge in the Apigee Community.

Use filters in a debug session

To use a filter in a new debug session:

  • In the hybrid UI: Select one of the available options in the Filters drop-down list, as described in Use the trace UI or choose "Custom Filter" and build your own with the syntax described above.
  • In the Apigee APIs: Add a filter object to the body of the debug session creation request, as described in Use the hybrid trace APIs.

Apigee hybrid does not support adding filters in the query string.

You cannot add a filter to a debug session once the session has started. To add a filter, you must create a new debug session.