Tutorial: Debug your APIs using request tracing

APPLIES TO: Consumption | Developer | Basic | Standard | Premium

This tutorial describes how to inspect (trace) request processing in Azure API Management. Tracing helps you debug and troubleshoot your API.

In this tutorial, you learn how to:

• Trace an example call
• Review request processing steps

Note

Currently, API request tracing isn't supported in the Basic v2 and Standard v2 tiers.

Prerequisites

• Learn the Azure API Management terminology.
• Complete the following quickstart: Create an Azure API Management instance.
• Complete the following tutorial: Import and publish your first API.

Verify allow tracing setting

To trace request processing, you must enable the Allow tracing setting for the subscription used to debug your API. To check in the portal:

1. Navigate to your API Management instance and select Subscriptions to review the settings.

   

2. If tracing isn't enabled for the subscription you're using, select the subscription and enable Allow tracing.

Warning

• Only allow tracing on subscriptions intended for debugging purposes. Sharing subscription keys with tracing allowed with unauthorized users could lead to disclosure of sensitive information contained in tracing logs such as keys, access tokens, passwords, internal hostnames, and IP addresses.
• In the test console, API Management automatically disables tracing 1 hour after it's enabled on a subscription.

Trace a call

1. Sign in to the Azure portal, and navigate to your API Management instance.

2. Select APIs.

3. Select Demo Conference API from your API list.

4. Select the Test tab.

5. Select the GetSpeakers operation.

6. Optionally check the value for the Ocp-Apim-Subscription-Key header used in the request by selecting the "eye" icon.

   Tip

   You can override the value of Ocp-Apim-Subscription-Key by retrieving a key for another subscription in the portal. Select Subscriptions, and open the context menu (...) for another subscription. Select Show/hide keys and copy one of the keys. You can also regenerate keys if needed. Then, in the test console, select + Add header to add an Ocp-Apim-Subscription-Key header with the new key value.

7. Select Trace.

   • If your subscription doesn't already allow tracing, you're prompted to enable it if you want to trace the call.

   • You can also choose to send the request without tracing.

     

Review trace information

1. After the call completes, go to the Trace tab in the HTTP response.

2. Select any of the following links to jump to detailed trace info: Inbound, Backend, Outbound, On error.

   

   • Inbound - Shows the original request API Management received from the caller and the policies applied to the request. For example, if you added policies in Tutorial: Transform and protect your API, they'll appear here.

   • Backend - Shows the requests API Management sent to the API backend and the response it received.

   • Outbound - Shows the policies applied to the response before sending back to the caller.

   • On error - Shows the errors that occurred during the processing of the request and the policies applied to the errors.

   Tip

   Each step also shows the elapsed time since the request is received by API Management.

3. On the Message tab, the ocp-apim-trace-location header shows the location of the trace data stored in Azure blob storage. If needed, go to this location to retrieve the trace. Trace data can be accessed for up to 24 hours.

   

Enable tracing using Ocp-Apim-Trace header

When making requests to API Management using curl, a REST client such as Postman, or a client app, enable tracing by adding the following request headers:

• Ocp-Apim-Trace - set value to true
• Ocp-Apim-Subscription-Key - set value to the key for a tracing-enabled subscription that allows access to the API

The response includes the Ocp-Apim-Trace-Location header, with a URL to the location of the trace data in Azure blob storage.

For information about customizing trace information, see the trace policy.

Next steps

In this tutorial, you learned how to:

• Trace an example call
• Review request processing steps

Advance to the next tutorial:

Use revisions