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 (you can send messages directly from the trace session — see "Tracing calls"). 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
The message sent to your backend service after the request flow has been executed.
- Response returned by your backend service
This data comes directly from your backend service 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.
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 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 from the summary list on the API proxies table.
- On the API detail page, click Trace and choose an environment (test or prod). If this button is grey, it indicates that you need to deploy your API.
- Click Start Trace Session. This runs a Trace session for 2 minutes. While the Trace session is running, messages are captured from live traffic.
- When you've capture enough messages click Stop Trace Session.
- Click on any of the captured messages to see detailed results.
To generate traffic for a trace
You can send GET requests to your API proxy from within the trace session. Alternatively, you can open the Apigee Console and direct requests to your API proxy (you're not limited to GET requests when you send requests from the Apigee Console).
Generating requests from the trace session
- 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.
You can click Send multiple times to generate as much traffic as you wish.
Generating requests from the Apigee Console
- Click "Send with the Apigee Console" in the Send Requests section.
A console will open in a new window displaying the base path of your API.
- Select an HTTP verb from the drop-down menu.
- Enter the path of the API resource.
- Click Send
- Switch back to the trace session.
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 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 HTTP headers send 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 trace results
Click Download Trace Session after you stop a tracing session.
Filters let you limit the trace so you only see the specific calls that 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 it 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 page.
- Enter a name and value into either the Header or Query fields. Blank fields are not evaluated.
You can add more filters by clicking the Add Filter button. You can delete filters by clicking the (X) button next to the filter.
If an application is not getting data or if it's taking very long to get data back from a target service, 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.