Edit

Tutorial: Debug your APIs using request tracing

  • Article

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 in the test console
  • Review request processing steps
  • Enable tracing for an API

Screenshot showing the API inspector.

Note

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

Prerequisites

Important

  • API Management request tracing can no longer be enabled by setting the Ocp-Apim-Trace header in a request and using the value of the Ocp-Apim-Trace-Location header in the response to retrieve the trace.
  • To improve security, tracing is now enabled at the level of an individual API by obtaining a time-limited token using the API Management REST API, and passing the token in a request to the gateway. For details, see later in this tutorial.
  • Take care when enabling tracing, as it can expose sensitive information in the trace data. Ensure that you have appropriate security measures in place to protect the trace data.

Trace a call in the portal

  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.

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.

Enable tracing for an API

You can enable tracing for an API when making requests to API Management using curl, a REST client such as Visual Studio Code with the REST Client extension, or a client app.

Enable tracing by the following steps using calls to the API Management REST API.

Note

The following steps require API Management REST API version 2023-05-01-preview or later. You must be assigned the Contributor or higher role on the API Management instance to call the REST API.

  1. Obtain trace credentials by calling the List debug credentials API. Pass the gateway ID in the URI, or use "managed" for the instance's managed gateway in the cloud. For example, to obtain trace credentials for the managed gateway, use a call similar to the following:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview

    In the request body, pass the full resource ID of the API that you want to trace, and specify purposes as tracing. By default the token credential returned in the response expires after 1 hour, but you can specify a different value in the payload.

    {
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes: ["tracing"]
}

    The token credential is returned in the response, similar to the following:

    {
      "token": "aid=api-name&p=tracing&ex=......."
}

  2. To enable tracing for a request to the API Management gateway, send the token value in an Apim-Debug-Authorization header. For example, to trace a call to the demo conference API, use a call similar to the following:

    curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."

  3. Depending on the token, the response contains different headers:

    • If the token is valid, the response includes an Apim-Trace-Id header whose value is the trace ID.
    • If the token is expired, the response includes an Apim-Debug-Authorization-Expired header with information about expiration date.
    • If the token was obtained for wrong API, the response includes an Apim-Debug-Authorization-WrongAPI header with an error message.

  4. To retrieve the trace, pass the trace ID obtained in the previous step to the List trace API for the gateway. For example, to retrieve the trace for the managed gateway, use a call similar to the following:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview

    In the request body, pass the trace ID obtained in the previous step.

    {
    "traceId": "<trace ID>"
}

    The response body contains the trace data for the previous API request to the gateway. The trace is similar to the trace you can see by tracing a call in the portal's test console.

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
  • Enable tracing for an API

Advance to the next tutorial:

Use revisions