Apigee's trace feature lets you review data on how messages are executed from the time a call is sent to your backend service to the response. The data shows how each policy is performing, how long it takes to execute, and exactly where things might have broken.
Here are some key data points:
- 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.
Each trace is broken down into these major steps:
- Original request received from client
Shows the verb and path of the message sent by the client which can be either originate from an app, API console or terminal. 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 server
The message sent to your backend sever after the request flow has been executed. - Response returned by your server
This data comes directly from your backend server to the gateway where the response flow is executed. During this step policies and conditions attached to the response flow are executed. - Final response sent to client
The message sent back to the original client (app, console or terminal) after the response flow has been executed.
Tracing calls
To trace a call you need to start a tracing session. Apigee will capture messages sent to your API from apps or other clients (such as consoles and terminals). If you don't have any live traffic you can generate some 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 from the summary list on the API tab.
- On the API detail page, click the Trace button and choose an environment. If this button is grey, it indicated that you need to deploy your API.
- Click Start in the Sample Live Calls controls. This starts a listening session.
- When you've capture enough messages click Stop.
- Click on any of the captured messages to see detailed results.
To generate traffic for a trace
- Click Open the Apigee Console button. A console will open in a new window displaying the base path of your API.
- You can click Send in the console to set a call to the root URL of your API or you can enter the path of a resource and send a call there.
- Switch back to the Apigee window and you'll see the call in the Captured Messages section.
- Click the message to see the details of the trace.
- Click the Next button 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 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 trace results
Click the download results button after you stop a tracing session.
Adding Filters
Filter let you limit the trace so you only see the specific calls you're interested in:
- HTTP headers - limits the trace to only calls that contain a specific header. This is a good way of helping you troubleshoot issues. You can send a header to your app developer and ask them to include in the call that is causing issues. Then Apigee will only record calls with that specific header so you can examine the results.
- Query parameters - only calls with a specific value of a parameter will be recorded.
To add a filter
- Open the Filter section of the Trace controls.
- Enter data into either the Header or Query fields. Blank fields are not evaluated.
You can add more filters by clicking the Add Filters button. You can delete filters by clicking the (X) button next to the filter.
Troubleshooting performance issues
If an application is not getting data or if it's taking very long to get data back from a target server, you should examine a sample of the last 10 calls sent through your API. Look at how long a message takes to reach the target (total response time) and how long it takes the data to get back to the app (target response time). Examine any calls that take significantly longer to execute to make sure that your traffic-control policies are working as expected. First, check the base path of each step in your flow and make sure that all calls are going to the correct target. Then, examine each policy. Depending on which policies you added to your flow, you should look for the following:
- Rate limiting: Make sure that a rate limit is being evaluated for each message.
- Caching: Make sure that all messages are being cached.
- Transformations: Make sure the message is being transformed correctly. If your target is expecting XML and your message is still in JSON, the call fails.
