API Services provides a Trace tool to enable you to debug end-to-end request and response flows. The trace results display request and response headers and payloads, policy execution, variable values, and any errors that may have occurred during the flow.
Key data points of use in troubleshooting:
- Timestamps: Use timestamps to see how long each step takes to execute. Comparing timestamps helps you isolate the policies that are taking the longest to execute that are slowing down your API calls.
- Base path: By verifying the base path, you can ensure that a policy is routing the message to correct server
- Results of policy execution: These results let you see if the message is being altered as expected, such as if the message is being transformed from XML to JSON, or if the message being cached.
One Trace session can support 10 request/response transactions through the selected API proxy. Each Trace session is broken down into the following major steps:
- Original request received from client
Displays the verb and URI path of the request from the client app. During this step, policies and conditions attached to the request flow are executed. The results indicate if policies are being executed properly in the order you defined for the flow. Properly executing policies are clearly indicated by checkmarks. Also, pay attention to the timestamp at the far right to see if any policy is taking longer than expected.
- Request sent to your backend service
Displays the request message sent to the backend service by the API proxy's TargetEndpoint.
- Response returned by the backend service
Displays the response headers and payload returned by the backend service. During this step, policies and conditions attached to the response flow are executed.
- Final response sent to client
The response message returned to the requesting client app once the response flow has executed.
To trace runtime calls, you need to start a tracing session in the Trace tool. While the session is active, API Services captures messages sent to your API . If you don't have any live traffic you can generate some directly from the trace session, by using the Apigee Console or by sending a cURL command using a terminal. The results that are displayed for each step in the call can be used not only make sure that your flows are executing properly but also to debug issues. For example, you can ask a developer to send calls to your API while you're listening. By examining the trace results you can find where calls are failing or which policies are not executing.
Note: You need to deploy your API before you can trace calls.
To trace calls
- Select an API proxy from the summary list on the API proxies table.
- On the API proxy Overview page, select Trace to access the Trace page. Select an environment (test or prod). If the environment option is inactive, it indicates that the API proxy is not deployed.
- Click Start Trace Session. The places the API proxy in 'debug mode', in which the API proxy records details of each step in the processing pipeline. While the Trace session is running, messages and contextual data are captured from live traffic.
- When you've capture enough messages click Stop Trace Session.
- A list of captured request/response transactions displays in the left menu. Click on any of the transactions to view detailed results.
Generating requests from the Trace UI
- Enter the proxy URL in the URL field of the Send requests section. The URL field is initialized with the base path of your API proxy. The method is set to GET (and cannot be changed).
- Click Send.
The processing time for each message appears in the Transactions section.
Click a message to see the details of the trace in the Transaction section (below the Send Requests section).
Click Next on the far-right of the window, to step through the trace.
At each step you can expand the results to get more detail. You can see the HTTP headers sent with the message by expanding the Headers section. You can view the payload of a message by expanding the Content section.
Downloading trace results
You can download an XML file of the trace results for viewing offline. The file shows the complete details of the listening session including the contents of all headers, variables and policies.
To download raw trace output, click Download Trace Session.
The Download Trace Session button is only enabled when the trace session is active. After the trace session expires or you click Stop Trace Session, the Download Trace Session button is disabled.