Merge pull request #289738 from dlepow/trace

[APIM] Update tracing steps

Author: JamesJBarnett

articles/api-management/api-management-howto-api-inspector.md

@@ -5,7 +5,7 @@ services: api-management
 author: dlepow
 ms.service: azure-api-management
 ms.topic: tutorial
-ms.date: 05/05/2024
+ms.date: 11/04/2024
 ms.author: danlep
 ms.custom: devdivchpfy22
 ---
@@ -36,11 +36,14 @@ In this tutorial, you learn how to:
 
 ## Trace a call in the portal
 
+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.
+
 1. Sign in to the [Azure portal](https://portal.azure.com), and navigate to your API Management instance.
-1. Select **APIs**.
-1. Select  **Demo Conference API** from your API list.
+1. Select **APIs** > **APIs**.
+1. Select  **Petstore API** from your API list.
 1. Select the **Test** tab.
-1. Select the **GetSpeakers** operation.
+1. Select the **Find pet by ID** operation.
+1. In the *petId* **Query parameter**, enter *1*.
 1. 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.
@@ -55,7 +58,7 @@ In this tutorial, you learn how to:
 
      :::image type="content" source="media/api-management-howto-api-inspector/response-trace-1.png" alt-text="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](transform-api.md), they'll appear here.
+    * **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.
 
     * **Backend** - Shows the requests API Management sent to the API backend and the response it received.
 
@@ -69,25 +72,31 @@ In this tutorial, you learn how to:
 
 ## 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. 
+The following high level steps are required to enable tracing for a request to API Management when using `curl`, a REST client such as Visual Studio Code with the REST Client extension, or a client app. Currently these steps must be followed using the [API Management REST API](/rest/api/apimanagement):
+
+1. Obtain a token credential for tracing.
+1. Add the token value in an `Apim-Debug-Authorization` request header to the API Management gateway.
+1. Obtain a trace ID in the `Apim-Trace-Id` response header.
+1. Retrieve the trace corresponding to the trace ID.
 
-Enable tracing by the following steps using calls to the API Management REST API.
+Detailed steps follow.
 
 > [!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.
+> * 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.
+> * For information about authenticating to the REST API, see [Azure REST API reference](/rest/api/azure). 
 
-1. Obtain trace credentials by calling the [List debug credentials](/rest/api/apimanagement/gateway/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:
+1. **Obtain a token credential** - 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:
 
     ```http
     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.
+    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. For example:
 
     ```json
     {
         "credentialsExpireAfter": PT1H,
-        "apiId": "<API resource ID>",
+        "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
         "purposes": ["tracing"]
     }
     ```
@@ -96,21 +105,27 @@ Enable tracing by the following steps using calls to the API Management REST API
 
     ```json
     {
-          "token": "aid=api-name&p=tracing&ex=......."
+          "token": "aid=api-name&......."
     }
     ```
 
-1. 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:
+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:
 
     ```bash
-    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=......."
+    curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."
     ```
-1. 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.
+
+1. Depending on the token, the response contains one of the following headers:
+    * If the token is valid, the response includes an `Apim-Trace-Id` header whose value is the trace ID, similar to the following:
+
+        ```http
+        Apim-Trace-Id: 0123456789abcdef....
+        ```
+        
     * 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.
+    * If the token was obtained for a different API, the response includes an `Apim-Debug-Authorization-WrongAPI` header with an error message.
 
-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 for the gateway. For example, to retrieve the trace for the managed gateway, use a call similar to the following:
+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:
 
     ```http
     POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
@@ -120,7 +135,7 @@ Enable tracing by the following steps using calls to the API Management REST API
 
     ```json
     {
-        "traceId": "<trace ID>"
+        "traceId": "0123456789abcdef...."
     }
     ```
     
@@ -134,7 +149,7 @@ For information about customizing trace information, see the [trace](trace-polic
 In this tutorial, you learned how to:
 
 > [!div class="checklist"]
-> * Trace an example call
+> * Trace an example call in the test conosle
 > * Review request processing steps
 > * Enable tracing for an API
 

includes/api-management-tracing-alert.md

@@ -2,10 +2,10 @@
 author: dlepow
 ms.service: azure-api-management
 ms.topic: include
-ms.date: 05/05/2024
+ms.date: 11/04/2024
 ms.author: danlep
 ---
 > [!IMPORTANT]
-> * API Management request tracing using the **Ocp-Apim-Trace** header in a request and using the value of the **Ocp-Apim-Trace-Location** response header is being deprecated.
-> * To improve 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).
+> * API Management no longer supports subscriptions for tracing or the **Ocp-Apim-Trace** header.
+> * 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).
 > * 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.