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.
The following image shows the process of creating a new 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.
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:
apigee-synchronizer(role: Apigee Synchronizer Manager)
apigee-udca(role: Apigee Analytics Agent)
For more information, see Create service accounts.
- Synchronizer access
- Clocks on all Synchronizer nodes should be in sync and in UTC
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:
- Start a new debug session
- View recent debug sessions
- Delete debug session data
- Download debug session data and view it offline
- Use filters
Use the trace APIs
The trace APIs section describes how to use the following APIs:
- Debug Sessions API (includes the Create Debug Sessions API, Delete Data Debug Sessions API, and List Debug Sessions API)
- Debug Session Data API (includes the Get Debug Session Data API and List Debug Session Data API)
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.|
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 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.
Filters support the same syntax that is used by Edge conditions, as described in Conditions reference. This includes:
- Logical AND (
&&) and OR (
- Path expressions
- Operators and Operands
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 && 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') && request.queryparam.param3 == 'Z' # Faults: fault.code != 'messaging.runtime.RouteFailed' fault.name == 'IPDeniedAccess'
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
filterobject 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.