Using Debug

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This section describes how to create and manage debug sessions, and view the request and response data using the Apigee UI and API.

Use Offline Debug to view and analyze debug sessions that were previously downloaded.

Creating a debug session

When you create a debug session, you can view the request and response data in the UI for requests created in the API or other external source.

Create a debug session using the Apigee UI or API, as described in the following sections.

New Proxy Editor

To create a debug session in the new Proxy Editor:

If you are using the Apigee UI in Cloud console: Select Proxy development > API Proxies.

If you are using the classic Apigee UI: Select Develop > API Proxies and in the Proxies pane, select the environment for the proxy you want to debug.
Select the API proxy that you want to debug. This displays the Proxy Editor Overview view.
Click the Debug tab at the top-left of the window.
Click the Start Debug Session at the top right of the Debug pane. This displays the Start debug session dialog.

In the dialog:
1. Select the Environment in which you want to run the debug session.
2. (Optional) From the Filter drop-down list, select a filter to apply to all transactions in the debug session you are creating. The default is None (All transactions), which includes all transactions in the debug data.
  For information on using filters, see Using filters in a debug session. For information about the built-in filters, see Using predefined filters.
3. Click Start.

The Apigee UI now displays the Debug session in progress view.

The debug session records requests for 10 minutes after you create the session. The Ends within field displays the amount of time remaining in the session.

You won't see any information displayed in the Debug pane until you send a request to the proxy you are debugging in the selected environment. environment for the debug session.

After you send the request, it is displayed at the bottom of the left-hand pane.

Start debug session dialog.

Note: During an active debug session, you can start another session in the Apigee UI. To do so, simply click Start Debug Session again.

Viewing the Gantt chart for a transaction

To view the details of a transaction (request and response) in the Debug view, click the row for the transaction, as shown in the image above.

This displays a Gantt chart in the right-hand pane that shows the steps in the request and response.

Gantt chart of transaction steps in right-hand pane.

The horizontal axis of the diagram denotes the times at which each step occurred, measured in milliseconds. Each step is represented by a rectangle that extends from the start time to the end time of the step.

You can step through a debug session using the Back and Next buttons at the bottom right of the debug pane. Click:

Back to move the selected row to the previous step in the chart.
Next to move the selected row to the next step in the chart.

In the example shown above, the chart displays two policies that are executed in the response:

ResponsePayload
Add CORS

You can click on either of these steps to view its details. For example, if you clicked the Add CORS policy, you would see details like the ones shown below displayed next to the Gantt chart.

Add CORS policy details.

If you then decided to change something in the policy configuration, you could then click Develop to switch to the Develop view, where you would see the same two policies in the Response PostFlow.

Viewing the Develop tab in relation to a debug session.

You can share a debug session with other users who have access to your organization and the necessary permissions. To do so, just send them the URL displayed in your browser when you are viewing the debug session. The link is only valid for 24 hours after the debug session is created.

Download a debug session

After a debug session is completed, you can download it so that you can analyze it later in the Offline Debug tool. To do so, click Download Session in the left-hand pane.

Download a debug session.

Note that a debug session is deleted within 24 hours of the time it is completed, so if you want to view the debug session after that time, you should download it before then.

When you download a debug session, the name of the download file has the form 'debug-{session ID}.json', where {session id} is the ID of the debug session. However, you can rename the file if you wish.

Classic Proxy Editor

To create a debug session in the classic Proxy Editor:

Sign in to the Apigee UI.
Select API Proxies from the main view.
Select the API proxy that you want to debug.

The Overview tab displays.
Click the Debug tab in the upper right of the page:

The Debug view displays:

In the Start a debug session panel:

From the Env drop-down list, select the environment + revision number of the API proxy you want to debug.

The following example shows the Start a debug session panel:

Start a debug session pane

(Optional) From the Filter drop-down list, select a filter to apply to all transactions in the debug session you are creating. The default is None, which includes all transactions in the debug data.
For information on using filters, see Using filters in a debug session. For information about the built-in filters, see Using predefined filters.

Click Start Debug Session.

The Apigee UI now displays details about the current debug session, including its ID, in the Debug details panel.

Although the UI created the debug session, you still need to send the request before there is any data to collect.

From the Debug details panel, you can do the following:

Icon	Function	Description
	Download	Download the active session's debug data, which you can then view offline.
	Return	Return to the previous panel, where you can start another debug session. The current debug session continues until it reaches its timeout or transaction count.
	Delete	Delete the currently selected debug session's data. This deletes the session's data, but does not stop the sessions.

There is a default timeout limit of 10 minutes for a debug session that you start in the UI (it's different for a session started with the API).

The clock starts running as soon as you click Start Debug Session, so you can choose to wait until after the next step before you click Start Debug Session to maximize the amount of data you gather.

In the Send Requests panel:
1. In the URL field, enter the endpoint that you want to send a request to. Optionally, append query string parameters to the URL. You cannot submit requests other than GET.
  How to find the endpoint URL
  1. Go to Admin > Environments > Groups
  2. The URL is the Hostname for the respective environment you'd like to run your debug session with.
2. Click Send.
  Apigee sends a request to the specified URL. Each time you click Send, the Apigee UI logs the request in the Debug details panel.
  
  The following example shows several successful requests (resulting in an HTTP status code of 200):
  
  Click Copy to copy the debug ID for future reference or queries.
  In addition, the UI displays debug data in the Transaction Map and Phase Details sections of the Send Requests panel, and populates the Proxy Endpoint, Request Headers, Request Content, and Properties sections, as the following example shows:
  
  For more information about the phases, transaction map, and other sections of the Send Requests view, see How to read a debug.
The debug session is now active and records data about all requests (unless they are filtered out). The session will remain active until either the timeout is reached or the number of requests recorded in the session is exceeded.
You can create any number of debug sessions in the UI. For more information, see Starting another debug session.

Starting another debug session in the UI

During an active debug session, you can start another session in the Apigee UI. To do this, click the back arrow icon () in the Debug details panel:

Back arrow that returns you to the Start a debug session panel

The UI returns to the Start a debug session panel, where you can start a new debug session.

When does a debug session end?

You cannot simply stop an active debug session. You can, however, delete an active session's data, as described in Deleting debug session data.

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

timeout: The length of time for which you collect data during a session. The default length depends on how you started the session (through the UI or API). The maximum value is 600 seconds (or 10 minutes).
Tip: You cannot configure the timeout when you create a new debug session with the Apigee UI. You can, however, set the timeout when you create a new debug session using the API.
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 either the timeout or the count is reached, the debug session for that Message Processor ends.

The following terms are used to describe the state of a debug session:

active session is a debug session that 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 timeout or exceeded its count; a completed session no longer records data about new requests and its data is deleted within 24 hours of the time at which the session ended.

How to read a debug

The debug tool has two main parts, the transaction map and the phase details:

The transaction map uses icons to mark each notable step that occurs during an API proxy transaction, including policy execution, conditional steps, and transitions. Hover over any icon to see summary information. The request flow steps appear along the top of the transaction map and response flow steps along the bottom.
The phase details section of the tool lists information about the proxy's internal processing, including variables that were set or read, request and response headers, and much more. Click any icon to see the phase details for that step.

Here's a sample debug tool map with the main proxy processing segments labeled:

Debug tool's transaction map

Debug diagram showing Begin proxy request to begin target request to begin target
response to begin proxy response to begin proxy post client flow

Transaction map legend

The following table describes the intent of the icons you will see in the transaction map. These icons mark each of the notable processing steps throughout the proxy flow.

Transaction map icons

	The client app that sends a request to the ProxyEndpoint of the API proxy.
	The circles mark transitional endpoints in the proxy flow. They are there when a request comes in from the client, when the request goes to the target, when the response comes back from the target, and when the response goes back to the client.
	The tall bars indicate the beginning of a flow segment in the API proxy flow. Flow segments are: ProxyEndpoint request, TargetEndpoint request, TargetEndpoint response, and ProxyEndpoint response. A segment includes the PreFlow, Conditional Flows, and PostFlow. See Configuring flows for more information.
	Indicates that Analytics actions have occurred in the background.
	A conditional flow that evaluates to true. For an introduction to conditional flows, see Configuring flows. Note that some conditions are Apigee-generated. For example, the following is an expression that Apigee uses to check if an error occurred in the ProxyEndpoint: `((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))`
	A conditional flow that evaluates to false. For an introduction to conditional flows, see Configuring flows. Note that some conditions are Apigee-generated. For example, the following is an expression that Apigee uses to check if an error occurred in the TargetEndpoint: `(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))`
	Policies. Each type of policy has a unique icon. This one is for the AssignMessage policy. These icons let you see where policies are executed in the proper order and if they are successful or not. You can click a policy icon to see the results of its execution and if they are expected or not. For example, you can see if the message was transformed properly or if it is being cached. Properly executing policies are clearly indicated by check-marks. In the case of an error, a red exclamation mark is displayed on the icon. Tip: Pay attention to the tooltip or the time line to see if any policy is taking longer than expected.
	The backend target called by the API proxy.
	The time line indicates how long (in milliseconds) that the processing time took to complete. Comparing the elapsed time segments helps you isolate the policies that are taking the longest to execute that are slowing down your API calls.
	The Epsilon indicates a time-span smaller than a millisecond.
	Disabled. Appears on a policy icon when a policy is disabled. A policy can be disabled with the public API. See API proxy configuration reference.
	Error. Appears on a policy icon when the Policy Step condition evaluates to false (see Flow variables and conditions), or on the RaiseFault policy icon whenever a RaiseFault policy executes.
	Skipped. Appears on a policy icon when the policy was not executed because the step condition evaluated to false. See Flow variables and conditions for more information.

Understanding the phase details

The Phase Details part of the tool tells you a lot about the state of your proxy at each processing step. Here are some of the details provided in the Phase Details. Click any icon in the debug tool to see details for the selected step, or use the Next/Back buttons to move from one step to another.

Phase Detail	Description
Proxy Endpoint	Indicates which ProxyEndpoint flow was selected for execution. An API proxy can have multiple named proxy endpoints.
Variables	Lists the flow variables that were read and assigned a value by a policy, See also Using flow variables. Note: An equals sign (=) indicates the value that was assigned to the variable. A crossed-out equals sign (≠) indicates that the variable could not be assigned a value because it is read-only or there was an error in policy execution. An empty field indicates that the variable value was read.
Request Headers	Lists the HTTP request headers.
Request Content	Shows the HTTP request body.
Properties	Properties represent the internal state of the API proxy. These are not shown by default.
Target Endpoint	Indicates which TargetEndpoint was selected for execution.
Response Headers	Lists the HTTP response headers.
Response Content	Shows the HTTP response body.
PostClientFlow	Shows information about the PostClientFlow, which executes after the request is returned to the requesting client app. Only MessageLogging policies can be attached to the PostClientFlow. The PostClientFlow is currently used primarily for measuring the time interval between the start and end timestamps for the response message.

Apigee API

To create a debug session using the API, issue a POST request to the following resource:

https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/debugsessions

Optionally, you can:

Set the length of a debug session (in seconds) by passing the timeout property as a query parameter or in the request body. If both are specified, the timeout value specified in the request body takes precedence.
Filter data in a debug session by passing the filter property in the request body.

The following example demonstrates how to create a debug session using the API.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

The following provides an example of the response:

{
  "name":"56382416-c4ed-4242-6381-591bbf2788cf",
  "validity":300,
  "count":10,
  "tracesize":5120,
  "timeout":"600"
}

Subsequent requests to your API proxy (until the session duration or maximum number of requests is reached) will be evaluated and potentially stored in the debug session data.

For more information, see the Create debug session API.

Setting the length of a debug session using the API

To set the length of a debug session using the API, include the following as a payload in your debug session creation request:

{
  "timeout":"debug_session_length_in_seconds"
}

The following example creates a debug session that is just 42 seconds long:

curl https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions"
  -X "POST" \
  -H "Authorization: Bearer $TOKEN" \
  -d ' {
    "timeout":"42"
  } '

You can set a session's timeout in debug session creation requests only; you cannot change a session's duration after you create the session.

The default value of timeout is 300 (5 minutes). The maximum value is 600 seconds (10 minutes).

Debugging with the debug tool

The debug lets you see a lot of internal details about an API proxy. For example:

You can see at a glance which policies are executing correctly or failing.
Let's say you noticed through one of the Analytics dashboards that one of your APIs is experiencing an unusual decrease in performance. Now, you can use Debug to help identify where the bottleneck is occurring. Debug gives the time, in milliseconds, that it takes for each processing step to complete. If you find one step is taking too long, you can take corrective action.
You can check headers that are being sent to the backend, view variables set by policies, and so on.
By verifying the base path, you can ensure that a policy is routing the message to the correct server.

Filtering data in a debug session

When you create a debug session, you can add a filter to that session so that Apigee returns only the data you want. A filter is a conditional statement that Apigee evaluates against request and response messages to determine if its debug data should be included in the debug session. For example, you can filter out all requests with an HTTP response code that is less than 599 or compare values in the request against custom variables.

Note the following:

Requests that are not included in a debug session because they are filtered out do not count towards the maximum number of transactions in the debug session.
Apigee 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 debug session.

Using filters

Use a filter when creating a debug session using the Apigee UI or API, as described in the following sections.

Classic Apigee UI

When you create a debug session in the UI, in the Filters drop-down list you can choose a predefined filter to apply in the Start a debug session panel or choose Custom Filter and build your own with the filter syntax.

Apigee API

To create a debug session with a filter using the API, include the following as a payload in your debug session creation request:

{
  "filter":"filter_body"
}

For information on constructing filters, see Filter syntax.

The following example creates a debug session that includes only transactions in which header A equals 42 and header B equals 43, or the fault code is ExpectedEOF:

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

You can define a filter in debug session creation requests only; you cannot add a filter to an existing debug session, and you cannot remove a filter from an active debug session.

Filter syntax

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

In addition, filters can access all flow variables 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'

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

Predefined UI filters

The Apigee UI provides a set of common filters so that you don't have to write your own custom filters. The predefined filters are as summarized in the following table.

Filter Name	Description
`Response Time Greater Than`	Checks for latency issues where: `target.duration` is the target latency, or the amount of time, in milliseconds, that a request takes to be sent to and received from the target (calculated as the difference between `target.received.end.timestamp` and `target.sent.start.timestamp`) `client.duration` is the client latency, or the amount of time, in milliseconds, that a request takes to be sent to and received from the client (calculated as the difference between `client.received.end.timestamp` and `client.sent.start.timestamp`) For example: target.duration > 420 && client.duration > 1000 For more information, see `client` and `target` in the Flow variables reference.
`Response Code`	Checks if the HTTP response code matches the specified value; for example: response.status.code <= 599 Tip: If you are receiving errors, try using `message.status.code` instead of `response.status.code`.
`Header`	Checks if the specified request header is equal to the specified value; for example: request.header.cache-control.1 == "16544"
`Path`	Checks if the request matches the specified path. You can use wildcard matching in your value; for example: request.path == /myproxy/customer/4*
`Query Param`	Checks if the specified request query parameter is equal to the specified value; for example: request.queryparam.lang == "language:en-us"
`Custom`	Lets you insert your own expressions. You can use any objects in the Flow variables reference and the syntax in Conditions reference. In addition, you can use custom variables. For more information about creating custom filters, see Filter syntax.

Viewing debug sessions

Apigee saves debug session data for 24 hours. You cannot configure this value; after 24 hours, the data will no longer be available. Before that time, you can view the debug sessions.

View recent debug sessions using the Apigee UI or API, as described in the following sections.

New Proxy Editor

To view debug sessions using the New Proxy Editor:

If you are using the Apigee UI in Cloud console: Select Proxy development > API Proxies.

If you are using the classic Apigee UI: Select Develop > API Proxies and in the Proxies pane, select the environment for the proxy you want to debug.
Select the proxy that you want to debug.
Click the Debug tab.
The Recent debug sessions displays a list of debug sessions that are available.
Click the link for the session you want to view.

Classic Proxy Editor

To view debug sessions using the Classic Proxy Editor:

Sign in to the Apigee UI.
Select API Proxies from the main view.
Select the proxy that you want to debug.
Click the Debug tab in the upper right of the Deployments view.
In the Recent debug sessions panel:
1. From the Env drop-down list, select the environment of the API proxy whose debug session you want to view.
2. From the Rev drop-down list, select the revision number of the API proxy whose debug session you want to view.
The Apigee UI displays a list of debug sessions that are available.
Click the link for the session you want to view.

The Apigee UI loads the debug session and populates the Send Requests panel with the debug data.

Selecting view options in the UI

In the Apigee UI, you can choose the view options for the debug session.

view options list

Option	Description
Show Disabled Policies	Show any disabled policies. A policy can be disabled with the public API. See API proxy configuration reference.
Show Skipped Phases	Show any phases that were skipped. A skipped phase occurs when policy was not executed because the step condition evaluated to false. See Conditions with flow variables for more information.
Show all FlowInfos	Represent transitions within a flow segment.
Automatically Compare Selected Phase	Compares the selected phase to the previous one. Turn this off to see only the selected phase.
Show Variables	Show or hide variables that were read and/or assigned a value.
Show Properties	Properties represent the internal state of the API proxy. (Hidden by default.)

Apigee API

Using the API, you can:

View all debug sessions
View all transactions for a debug session
View transaction data for a debug session

View all debug sessions using the API

To view all recent debug sessions defined for an API proxy revision in an environment, issue a GET request to the following resource:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions

Optionally, you can specify one of the following query parameters to control the amount of data returned:

pageSize: Maximum number of debug sessions to list. The page size defaults to 25.
pageToken: Page token, returned from a previous call, that you can use to retrieve the next page.

The following example demonstrates how to view the debug sessions for revision 1 of the helloworld API proxy in the test environment.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

The response includes a sessions object that contains a list of currently active debug sessions, as shown in the following example:

{
  "sessions": [
    {
      "id": "a423ac73-0902-4cfa-4242-87a353a84d87",
      "timestamp_ms": 1566330186000
    },
    {
      "id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
      "timestamp_ms": 1566330286000
    }
  ]
}

Only debug sessions that contain at least one transaction are included in the response; debug sessions that do not have any transactions are not included in this list.

For more information, see List Debug sessions API.

View all transactions for a debug session using the API

To view a list of transactions for a debug session, issue a GET request to the following resource:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Where debugsession is the ID of a debug session returned when you view debug sessions.

The following example demonstrates how to view the transactions for a debug session for revision 1 of the helloworld API in the test environment.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

The response includes an array of transaction IDs, as shown in the following example:

[
  "myorg-test-ver-5qxdb-64",
  "myorg-test-ver-5qxdb-65",
  "myorg-test-ver-5qxdb-66",
  "myorg-test-ver-5qxdb-67",
  "myorg-test-ver-5qxdb-68",
  "myorg-test-ver-5qxdb-69",
  "myorg-test-ver-5qxdb-70",
  "myorg-test-ver-5qxdb-71",
  "myorg-test-ver-5qxdb-72"
]

For more information, see List debug session data API.

Viewing transaction data for a debug session using the API

To view transaction data for a debug session, issue a GET request to the following resource:

https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions/{debugsession}/data/{transactionId}

Where debugsession is the ID of a debug session returned when you view debug sessions and transactionId is the transaction ID returned when you View a list of transactions for a debug session.

The transaction data saved during a debug session is formatted in JSON. You can load this data in the Offline Debug tool.

The following example demonstrates how to download the transaction data for a debug session for revision 1 of the helloworld API in the test environment.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data/myorg-test-ver-5qxdb-64" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

The response consists of a JSON payload that contains the data for the specified transaction, as described in Download data structure.

Debug data contains all information about the request and response for each part of the flow in a proprietary JSON format. You can save this data and later use it in the Offline Debug tool.

If no requests were added to the session before it ended, then the response will look like the following:

[]

For more information, see Get debug session data API.

Downloading debug session data

You can download a file of raw debug results for offline viewing. The downloaded file shows the complete details of the debug session including the contents of all headers, variables, and policies.

Debug session data is available to download or view in the UI for 24 hours only. After that point, Apigee deletes the session data.

New Proxy Editor

To download the current debug session in the new Proxy Editor, click Download Session in the left-hand pane of the Debug view.

Download a debug session.

Note that a debug session is deleted within 24 hours of the time it is completed, so if you want to view the debug session after that time, you need to download it before then.

Classic Proxy Editor

To download the current debug session's data using the classic Proxy Editor:

Active session: Click the Download icon ( ) in the Debug details panel.
Previous session: Click the name of the session in the Recent debug sessions panel, as described in Viewing debug sessions. Then click in the Debug details panel.

Apigee API

To view the IDs of all transactions for the current debug session using the Apigee API, enter the following command:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data

where SESSION_ID is the ID for the debug session you want to download.

See List the transaction IDs from a debug session.

To get the debug data for a transaction using the Apigee API, enter the following command:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data/TRANSACTION_ID

Download data structure

The download structure of the debug session data is different for the Apigee UI and Apigee API.

Classic Apigee UI

When you download data using the Apigee UI, the data structure:

Includes all transactions in the entire session
Stores transactions in a Messages array
Includes metadata about the session (as a DebugSession object)

Apigee API

You cannot use the Apigee API to view an entire sessions' data at one time; you can only use the API to view individual transaction data, as described in Viewing debug sessions.

For example:

{
  "completed": true,
  "point": [
    ...
  ...
}

Download data examples

The following example highlights a DebugSession metadata object in the downloaded data. This object is following by the Messages array that contains the transactions in the session.

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

If the debug session did not include any requests, then the Message array is empty, as the following example shows:

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": []
}

Deleting data for a debug session

Delete data for a debug session using the Apigee UI or API, as described in the following sections.

New Proxy Editor

To delete a debug session in the new Proxy Editor:

Select the row for the session you want to delete.
Click the three-dot menu at the end of the row and select Delete.

Classic Proxy Editor

Click in the Debug details panel for the debug session.

Apigee API

To delete all debug session data using the API, issue a DELETE request to the following resource:

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

Where debugsession is the ID of a debug session returned when you view debug sessions.

The following example demonstrates how to delete debug session data for revision 1 of the helloworld API in the test environment.

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

If successful, the response body will be empty.

Debug session data is persisted for 24 hours only. If you do not explicitly delete it before that time, then Apigee deletes it for you.

Using Debug

Creating a debug session

New Proxy Editor

Viewing the Gantt chart for a transaction

Share a debug session

Download a debug session

Classic Proxy Editor

How to find the endpoint URL

Starting another debug session in the UI

When does a debug session end?

How to read a debug

Transaction map legend

Understanding the phase details

Apigee API

Setting the length of a debug session using the API

Debugging with the debug tool

Filtering data in a debug session

Using filters

Classic Apigee UI

Apigee API

Filter syntax

Predefined UI filters

Viewing debug sessions

New Proxy Editor

Classic Proxy Editor

Selecting view options in the UI

Apigee API

View all debug sessions using the API

View all transactions for a debug session using the API

Viewing transaction data for a debug session using the API

Downloading debug session data

New Proxy Editor

Classic Proxy Editor

Apigee API

Download data structure

Classic Apigee UI

Apigee API

Download data examples

Deleting data for a debug session

New Proxy Editor

Classic Proxy Editor

Apigee API