Tutorial: Debug your APIs using request tracing

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

API inspector

Prerequisites

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.

    Allow tracing for subscription

  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.

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.

      Screenshot showing configure API 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.

    Review response trace

    • 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.

    Trace location in Azure Storage

Next steps

In this tutorial, you learned how to:

  • Trace an example call
  • Review request processing steps

Advance to the next tutorial: