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
:::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":::
31
32
32
33
## Prerequisites
33
34
34
-
+ Learn the [Azure API Management terminology](api-management-terminology.md).
35
-
+ Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
36
-
+ Complete the following tutorial: [Import and publish your first API](import-and-publish.md).
37
-
35
+
- Learn the [Azure API Management terminology](api-management-terminology.md).
36
+
- Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
37
+
- Complete the following tutorial: [Import and publish your first API](import-and-publish.md).
Follow these steps to trace an API request in the test console in the portal. This example assumes that you [imported](import-and-publish.md) a sample API in a previous tutorial. You can follow similar steps with a different API that you imported.
44
44
@@ -49,30 +49,28 @@ Follow these steps to trace an API request in the test console in the portal. Th
49
49
1. Select the **Find pet by ID** operation.
50
50
1. In the *petId***Query parameter**, enter *1*.
51
51
1. Optionally check the value for the **Ocp-Apim-Subscription-Key** header used in the request by selecting the "eye" icon.
52
-
> [!TIP]
53
-
> 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.
54
52
55
-
1. Select **Trace**.
53
+
> [!TIP]
54
+
>
55
+
> You can override the value of **Ocp-Apim-Subscription-Key** by retrieving a key for another subscription in the Azure 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.
56
56
57
+
1. Select **Trace**.
57
58
58
59
## Review trace information
59
60
60
61
1. After the call completes, go to the **Trace** tab in the **HTTP response**.
61
-
1. 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](transform-api.md), they appear here.
66
-
67
-
***Backend** - Shows the requests API Management sent to the API backend and the response it received.
62
+
1. Select any of the following links to jump to detailed trace information: **Inbound**, **Backend**, **Outbound**, **On error**.
68
63
69
-
***Outbound** - Shows the policies applied to the response before sending back to the caller.
64
+
:::image type="content" source="media/api-management-howto-api-inspector/response-trace-1.png" alt-text="Screenshot showing the review response trace.":::
70
65
71
-
***On error** - Shows the errors that occurred during the processing of the request and the policies applied to the errors.
72
-
73
-
> [!TIP]
74
-
> Each step also shows the elapsed time since the request is received by API Management.
66
+
-**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](transform-api.md), they appear here.
67
+
-**Backend**. Shows the requests API Management sent to the API backend and the response it received.
68
+
-**Outbound**. Shows the policies applied to the response before sending back to the caller.
69
+
-**On error**. Shows the errors that occurred during the processing of the request and the policies applied to the errors.
75
70
71
+
> [!TIP]
72
+
>
73
+
> Each step also shows the elapsed time since API Management receives the request.
76
74
77
75
## Enable tracing for an API
78
76
@@ -86,79 +84,76 @@ The following high level steps are required to enable tracing for a request to A
86
84
Detailed steps follow.
87
85
88
86
> [!NOTE]
89
-
> * These 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.
90
-
> * For information about authenticating to the REST API, see [Azure REST API reference](/rest/api/azure).
87
+
>
88
+
> - These 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.
89
+
> - For information about authenticating to the REST API, see [Azure REST API reference](/rest/api/azure).
91
90
92
-
1.**Obtain a debug token** - Call the API Management gateway's [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. In the URI, enter "managed" for the instance's managed gateway in the cloud, or the gateway ID for a self-hosted gateway. For example, to obtain trace credentials for the instance's managed gateway, use a request similar to the following:
91
+
1.**Obtain a debug token**. Call the API Management gateway's [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. In the URI, enter *managed* for the instance's managed gateway in the cloud, or the gateway ID for a self-hosted gateway. For example, to obtain trace credentials for the instance's managed gateway, use a request similar to the following example:
93
92
94
-
```http
95
-
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
96
-
```
93
+
```http
94
+
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
95
+
```
97
96
98
-
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. Note that the expiry time is limited to a maximum of 1 hour. For example:
In the request body, pass the full resource ID of the API that you want to trace. Specify `purposes` as `tracing`. By default, the token credential returned in the response expires after 1 hour. You can specify a different value in the payload. The expiry time is limited to a maximum of 1 hour. For example:
107
98
108
-
> [!NOTE]
109
-
> The `apiId` can only be pulled from the full resource ID, not the name displayed in the portal.
> The `apiId` can only be pulled from the full resource ID, not the name displayed in the Azure portal.
112
109
110
+
Get apiId:
113
111
114
-
```azurecli
115
-
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
116
-
```
112
+
```azurecli
113
+
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
114
+
```
117
115
118
-
The debug credential is returned in the response, similar to the following:
116
+
The debug credential is returned in the response, similar to the following example:
119
117
120
-
```json
121
-
{
122
-
"token": "aid=api-name&......."
123
-
}
124
-
```
118
+
```json
119
+
{
120
+
"token": "aid=api-name&......."
121
+
}
122
+
```
125
123
126
-
1. **Add the token value in a request header** - 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 Petstore API that you imported in a previous tutorial, you might use a request similar to the following:
124
+
1.**Add the token value in a request header**. 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 Petstore API that you imported in a previous tutorial, you might use a request similar to the following example:
1. **Evaluate the response** - The response can contain one of the following headers depending on the state of the debug token:
135
-
* If the debug token is valid, the response includes an `Apim-Trace-Id` header whose value is the trace ID, similar to the following:
132
+
1.**Evaluate the response**. The response can contain one of the following headers depending on the state of the debug token:
136
133
137
-
```http
138
-
Apim-Trace-Id: 0123456789abcdef....
139
-
```
140
-
141
-
* If the debug token is expired, the response includes an `Apim-Debug-Authorization-Expired` header with information about expiration date.
142
-
* If the debug token was obtained for a different API, the response includes an `Apim-Debug-Authorization-WrongAPI` header with an error message.
134
+
| Header in response | Explanation |
135
+
|:-------------------|:------------|
136
+
|`Apim-Trace-Id`| Debug token valid. The value is the trace ID, such as: `Apim-Trace-Id: 0123456789abcdef....`|
137
+
|`Apim-Debug-Authorization-Expired`| Token is expired. Header includes information about expiration date. |
138
+
|`Apim-Debug-Authorization-WrongAPI`| Token obtained for a different API. Header includes an error message. |
143
139
144
-
1. **Retrieve the trace** - Pass the trace ID obtained in the previous step to the gateway's [List trace](/rest/api/apimanagement/gateway/list-trace) API. For example, to retrieve the trace for the managed gateway, use a request similar to the following:
140
+
1.**Retrieve the trace**. Pass the trace ID obtained in the previous step to the gateway's [List trace](/rest/api/apimanagement/gateway/list-trace) API. For example, to retrieve the trace for the managed gateway, use a request similar to the following example:
145
141
146
-
```http
147
-
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
148
-
```
142
+
```http
143
+
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
144
+
```
149
145
150
-
In the request body, pass the trace ID obtained in the previous step.
146
+
In the request body, pass the trace ID obtained in the previous step.
151
147
152
-
```json
153
-
{
154
-
"traceId": "0123456789abcdef...."
155
-
}
156
-
```
148
+
```json
149
+
{
150
+
"traceId": "0123456789abcdef...."
151
+
}
152
+
```
157
153
158
-
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.
154
+
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.
159
155
160
-
161
-
### Example `.http` file for VS Code REST Client extension
156
+
### Example http file for VS Code REST Client extension
162
157
163
158
To help automate these steps with the [Visual Studio Code REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension, you can use the following example `.http` file:
Copy file name to clipboardExpand all lines: includes/api-management-tracing-alert.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,10 @@
2
2
author: dlepow
3
3
ms.service: azure-api-management
4
4
ms.topic: include
5
-
ms.date: 11/04/2024
5
+
ms.date: 01/28/2026
6
6
ms.author: danlep
7
7
---
8
8
> [!IMPORTANT]
9
-
> * API Management no longer supports subscriptions for tracing or the **Ocp-Apim-Trace** header.
10
-
> * To improve API security, tracing can now be 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 [Enable tracing of an API](../articles/api-management/api-management-howto-api-inspector.md#enable-tracing-for-an-api).
11
-
> * 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.
9
+
> - API Management no longer supports subscriptions for tracing or the **Ocp-Apim-Trace** header.
10
+
> - To improve API security, tracing can now be enabled at the level of an individual API. Obtain a time-limited token using the API Management REST API, and pass the token in a request to the gateway. For details, see [Enable tracing of an API](../articles/api-management/api-management-howto-api-inspector.md#enable-tracing-for-an-api).
11
+
> - Take care when enabling tracing. It can expose sensitive information in the trace data. Ensure that you have appropriate security measures in place to protect the trace data.
0 commit comments