Debug overview

Stay organized with collections Save and categorize content based on your preferences.

You're viewing Apigee X documentation.
View Apigee Edge documentation.

Debug is a tool for troubleshooting and monitoring API proxies running on Apigee. The Debug tool lets you probe the details of each step through an API proxy flow. Apigee lets you collect debug 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 for debugging and troubleshooting during API proxy development and deployment.

Using Debug

Create and manage debug sessions using the Debug tool using the UI or API, as described in Using Debug. Alternatively, you can download debug sessions and view and analyze them offline, as described in Using Offline Debug.

Apigee Support use of Debug

Only customers can trigger a debug session, but Apigee Support can access non-deleted past debug sessions during the course of a support case to help troubleshoot proxy-specific issues.

Note the following:

  • Apigee Support has read-only permission to Debug data.
  • Apigee Support may request that you run a debug to capture information about an issue, and that you provide the debug session ID or a link to the debug session so that Support may review the captured debug. Since saved debug sessions are valid for only 24 hours, we recommend that you download the debug session and attach it to the case opened with Support to enable offline viewing.

For Apigee hybrid users

If you are using Apigee hybrid, review the following sections.

Debug architecture

The following illustrates the process of creating a new debug session:

A high-level view of a request to start a debug session: 
    1. You initiate a request to start a debug session, using the UI or API.
    2. The management plane issues a debug session creation request to the runtime plane using the pub/sub model. 
    3. The Synchronizer, which subscribes to debug session notifications, propagates the creation request to the Message Processors.
    4. The MPs collect debug data and stream it to a data collection pod.
    5. fluentd immediately writes the debug data to the pod's file system.
    6. The UDCA polls the pod's file system for new data files.
    7. When it finds a new data file, UDCA uploads it to the UAP service. 
    8. You can then access the data via Apigee services such as the Apigee hybrid UI or the Apigee APIs.

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


If you are using Apigee hybrid, before you can use debug 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 for hybrid v1.3, see Create service accounts, for your platform as follows: