You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This tutorial describes how to inspect (trace) request processing in Azure API Management. Tracing helps you debug and troubleshoot your API.
16
18
17
19
In this tutorial, you learn how to:
@@ -22,20 +24,14 @@ In this tutorial, you learn how to:
22
24
23
25
:::image type="content" source="media/api-management-howto-api-inspector/api-inspector-002.png" alt-text="Screenshot showing the API inspector." lightbox="media/api-management-howto-api-inspector/api-inspector-002.png":::
+ Learn the [Azure API Management terminology](api-management-terminology.md).
28
32
+ Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
29
33
+ Complete the following tutorial: [Import and publish your first API](import-and-publish.md).
30
34
31
-
## Verify allow tracing setting
32
-
33
-
To trace request processing, you must enable the **Allow tracing** setting for the subscription used to debug your API. To check in the portal:
34
-
35
-
1. Navigate to your API Management instance and select **Subscriptions** to review the settings.
36
-
37
-
:::image type="content" source="media/api-management-howto-api-inspector/allow-tracing-1.png" alt-text="Screenshot showing how to allow tracing for subscription." lightbox="media/api-management-howto-api-inspector/allow-tracing-1.png":::
38
-
1. If tracing isn't enabled for the subscription you're using, select the subscription and enable **Allow tracing**.
@@ -52,10 +48,6 @@ To trace request processing, you must enable the **Allow tracing** setting for t
52
48
53
49
1. Select **Trace**.
54
50
55
-
* If your subscription doesn't already allow tracing, you're prompted to enable it if you want to trace the call.
56
-
* You can also choose to send the request without tracing.
57
-
58
-
:::image type="content" source="media/api-management-howto-api-inspector/06-debug-your-apis-01-trace-call-1.png" alt-text="Screenshot showing configure API tracing." lightbox="media/api-management-howto-api-inspector/06-debug-your-apis-01-trace-call-1.png":::
59
51
60
52
## Review trace information
61
53
@@ -75,18 +67,66 @@ To trace request processing, you must enable the **Allow tracing** setting for t
75
67
> [!TIP]
76
68
> Each step also shows the elapsed time since the request is received by API Management.
77
69
78
-
1. 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.
79
70
80
-
:::image type="content" source="media/api-management-howto-api-inspector/response-message-1.png" alt-text="Trace location in Azure Storage":::
71
+
## Enable tracing using a REST client
72
+
73
+
You can enable tracing for an API when making requests to API Management using `curl`, a REST client such as VSCode with the REST Client extension, or a client app.
74
+
75
+
> [!IMPORTANT]
76
+
> API Management request tracing is no longer 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.
77
+
78
+
Enable tracing by the following flow using calls to the API Management REST API.
79
+
80
+
> [!NOTE]
81
+
> The following steps require API Management REST API version 2023-05-01-preview or later.
82
+
83
+
1. Obtain trace credentials by calling the [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. Pass the gateway resource ID in the URI, or use "managed" for the instance's managed gateway. for cloud in URI, and API that you want to trace in payload. For example:
84
+
85
+
```http
86
+
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/{gatewayId}/listTrace?api-version=2023-05-01-preview
Pass the full resource ID of the API in the payload, 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.
91
+
92
+
```json
93
+
{
94
+
"credentialsExpireAfter": PT1H,
95
+
"apiId": "<API resource ID>",
96
+
"purposes: ["tracing"]
97
+
}
98
+
```
99
+
100
+
The token credential is returned in the response, similar to the following:
101
+
102
+
```json
103
+
{
104
+
"token": "aid=api-name&p=tracing&ex=......."
105
+
}
106
+
```
107
+
108
+
1. To enable tracing, send the token value in an `Apim-Debug-Authorization` header of an API request.
109
+
110
+
* If the token is valid, the response contains an `Apim-Trace-Id` header whose value is the trace ID.
111
+
* If the token is expired, the response contains an `Apim-Debug-Authorization-Expired` header with information about expiration date.
112
+
* If the token was obtained for wrong API, the response contains an `Apim-Debug-Authorization-WrongAPI` header with an error message
113
+
114
+
1. To retrieve the trace, pass the trace ID obtained in the previous step to the [List trace](/rest/api/apimanagement/gateway/list-trace) API:
81
115
82
-
## Enable tracing using Ocp-Apim-Trace header
116
+
```http
117
+
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
118
+
```
83
119
84
-
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:
120
+
with body
85
121
86
-
***Ocp-Apim-Trace** - set value to `true`
87
-
***Ocp-Apim-Subscription-Key** - set value to the key for a tracing-enabled subscription that allows access to the API
122
+
```json
123
+
{
124
+
"traceId": "<trace ID>"
125
+
}
126
+
```
127
+
128
+
The response body contains the trace data for the previous API request to the gateway.
88
129
89
-
The response includes the **Ocp-Apim-Trace-Location** header, with a URL to the location of the trace data in Azure blob storage.
90
130
91
131
For information about customizing trace information, see the [trace](trace-policy.md) policy.
When you publish APIs through Azure API Management, it's easy and common to secure access to those APIs by using subscription keys. Client applications that need to consume the published APIs must include a valid subscription key in HTTP requests when they make calls to those APIs. To get a subscription key for accessing APIs, a subscription is required. For more information about subscriptions, see [Subscriptions in Azure API Management](api-management-subscriptions.md).
15
17
16
18
This article walks through the steps for creating subscriptions in the Azure portal.
@@ -29,13 +31,13 @@ To take the steps in this article, the prerequisites are as follows:
29
31
1. Navigate to your API Management instance in the [Azure portal](https://portal.azure.com).
30
32
1. In the left menu, under **APIs**, select **Subscriptions** > **Add subscription**.
31
33
1. Provide a **Name** and optional **Display name** of the subscription.
32
-
1. Optionally, select **Allow tracing** to enable tracing for debugging and troubleshooting APIs. [Learn more](api-management-howto-api-inspector.md)
1. Select a **Scope** of the subscription from the dropdown list. [Learn more](api-management-subscriptions.md#scope-of-subscriptions)
36
35
1. Optionally, choose if the subscription should be associated with a **User** and whether to send a notification for use with the developer portal.
37
36
1. Select **Create**.
38
37
38
+
> [!IMPORTANT]
39
+
> The **Allow tracing** setting in subscriptions is deprecated. Tracing can now be enabled for specific APIs. [Learn more](api-management-howto-api-inspector.md)
40
+
39
41
:::image type="content" source="media/api-management-howto-create-subscriptions/create-subscription.png" alt-text="Screenshot showing how to create an API Management subscription in the portal.":::
40
42
41
43
After you create the subscription, it appears in the list on the **Subscriptions** page. Two API keys are provided to access the APIs. One key is primary, and one is secondary.
The `trace` policy adds a custom trace into the request tracing output in the test console, Application Insights telemetries, and/or resource logs.
15
17
16
-
- The policy adds a custom trace to the [request tracing](./api-management-howto-api-inspector.md) output in the test console when tracing is triggered, that is, `Ocp-Apim-Trace` request header is present and set to `true` and `Ocp-Apim-Subscription-Key` request header is present and holds a valid key that allows tracing.
18
+
- The policy adds a custom trace to the [request tracing](./api-management-howto-api-inspector.md) output in the test console when tracing is triggered.
17
19
- The policy creates a [Trace](../azure-monitor/app/data-model-complete.md#trace) telemetry in Application Insights, when [Application Insights integration](./api-management-howto-app-insights.md) is enabled and the `severity` specified in the policy is equal to or greater than the `verbosity` specified in the [diagnostic setting](./diagnostic-logs-reference.md).
18
20
- The policy adds a property in the log entry when [resource logs](./api-management-howto-use-azure-monitor.md#resource-logs) are enabled and the severity level specified in the policy is at or higher than the verbosity level specified in the [diagnostic setting](./diagnostic-logs-reference.md).
19
21
- The policy is not affected by Application Insights sampling. All invocations of the policy will be logged.
0 commit comments