[APIM] Update tracing steps

Author: gitName

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

@@ -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.
@@ -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 [](). If you want to test the REST APIs, use the "Try It" functionality in the API Management REST API.
 
-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 [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. Pass the gateway ID for a self-hosted gateway in the URI, or specify "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:
 
     ```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"]
     }
     ```
@@ -100,17 +109,28 @@ Enable tracing by the following steps using calls to the API Management REST API
     }
     ```
 
-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 call 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&p=tracing&ex=......."
     ```
+
+    > [!NOTE]
+    > Information the user should notice even if skimming
+
 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.
+    * If the token is valid, the response includes an `Apim-Trace-Id` header whose value is the trace ID. For example:
+
+        ```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.
 
-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 [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:
 
     ```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 +140,7 @@ Enable tracing by the following steps using calls to the API Management REST API
 
     ```json
     {
-        "traceId": "<trace ID>"
+        "traceId": "0123456789abcdef...."
     }
     ```
     
@@ -134,7 +154,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