Merge pull request #270598 from dlepow/tr2

American-Dipper · web-flow · commit 13b550e2f8ff · 2024-05-06T13:59:11.000-07:00
[APIM] v2 tracing
diff --git a/articles/api-management/api-management-debug-policies.md b/articles/api-management/api-management-debug-policies.md
@@ -26,7 +26,7 @@ This article describes how to debug API Management policies using the [Azure API
 
 ## Restrictions and limitations
 
-* This feature uses the built-in (service-level) all-access subscription (display name "Built-in all-access subscription") for debugging. The [**Allow tracing**](api-management-howto-api-inspector.md#verify-allow-tracing-setting) setting must be enabled in this subscription.
+* This feature uses the built-in (service-level) all-access subscription (display name "Built-in all-access subscription") for debugging. 
 
 [!INCLUDE [api-management-tracing-alert](../../includes/api-management-tracing-alert.md)]
 
diff --git a/articles/api-management/api-management-howto-api-inspector.md b/articles/api-management/api-management-howto-api-inspector.md
@@ -5,7 +5,7 @@ services: api-management
 author: dlepow
 ms.service: api-management
 ms.topic: tutorial
-ms.date: 03/26/2024
+ms.date: 05/05/2024
 ms.author: danlep
 ms.custom: devdivchpfy22
 ---
@@ -19,8 +19,9 @@ This tutorial describes how to inspect (trace) request processing in Azure API M
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
-> * Trace an example call
+> * Trace an example call in the test console
 > * Review request processing steps
+> * Enable tracing for an API
 
 :::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":::
 
@@ -32,18 +33,10 @@ In this tutorial, you learn how to:
 + Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
 + Complete the following tutorial: [Import and publish your first API](import-and-publish.md).
 
-## Verify allow tracing setting
-
-To trace request processing, you must enable the **Allow tracing** setting for the subscription used to debug your API. To check in the portal:
-
-1. Navigate to your API Management instance and select **Subscriptions** to review the settings.
-
-   :::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":::
-1. If tracing isn't enabled for the subscription you're using, select the subscription and enable **Allow tracing**.
 
 [!INCLUDE [api-management-tracing-alert](../../includes/api-management-tracing-alert.md)]
 
-## Trace a call
+## Trace a call in the portal
 
 1. Sign in to the [Azure portal](https://portal.azure.com), and navigate to your API Management instance.
 1. Select **APIs**.
@@ -56,10 +49,6 @@ To trace request processing, you must enable the **Allow tracing** setting for t
 
 1. Select **Trace**. 
 
-    * If your subscription doesn't already allow tracing, you're prompted to enable it if you want to trace the call. 
-    * You can also choose to send the request without tracing.
-
-      :::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":::
 
 ## Review trace information
 
@@ -79,18 +68,66 @@ To trace request processing, you must enable the **Allow tracing** setting for t
     > [!TIP]
     > Each step also shows the elapsed time since the request is received by API Management.
 
-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.
 
-     :::image type="content" source="media/api-management-howto-api-inspector/response-message-1.png" alt-text="Trace location in Azure Storage":::
+## 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](/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:
+
+    ```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.
+
+    ```json
+    {
+        "credentialsExpireAfter": PT1H,
+        "apiId": "<API resource ID>",
+        "purposes: ["tracing"]
+    }
+    ```
+        
+    The token credential is returned in the response, similar to the following:
+
+    ```json
+    {
+          "token": "aid=api-name&p=tracing&ex=......."
+    }
+    ```
+
+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:
+
+    ```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=......."
+    ```
+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 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:
 
-## Enable tracing using Ocp-Apim-Trace header
+    ```http
+    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
+    ```
 
-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:
+    In the request body, pass the trace ID obtained in the previous step.
 
-* **Ocp-Apim-Trace** - set value to `true`
-* **Ocp-Apim-Subscription-Key** - set value to the key for a tracing-enabled subscription that allows access to the API
+    ```json
+    {
+        "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.
 
-The response includes the **Ocp-Apim-Trace-Location** header, with a URL to the location of the trace data in Azure blob storage.
 
 For information about customizing trace information, see the [trace](trace-policy.md) policy.
 
@@ -101,6 +138,7 @@ In this tutorial, you learned how to:
 > [!div class="checklist"]
 > * Trace an example call
 > * Review request processing steps
+> * Enable tracing for an API
 
 Advance to the next tutorial:
 
diff --git a/articles/api-management/api-management-howto-create-subscriptions.md b/articles/api-management/api-management-howto-create-subscriptions.md
@@ -17,6 +17,9 @@ When you publish APIs through Azure API Management, it's easy and common to secu
 
 This article walks through the steps for creating subscriptions in the Azure portal.
 
+> [!IMPORTANT]
+> The **Allow tracing** setting in subscriptions to enable debug traces is deprecated. To improve security, tracing can now be enabled for specific API requests to API Management. [Learn more](api-management-howto-api-inspector.md#enable-tracing-for-an-api)
+
 ## Prerequisites
 
 To take the steps in this article, the prerequisites are as follows:
@@ -31,12 +34,6 @@ To take the steps in this article, the prerequisites are as follows:
 1. Navigate to your API Management instance in the [Azure portal](https://portal.azure.com).
 1. In the left menu, under **APIs**, select **Subscriptions** > **Add subscription**.
 1. Provide a **Name** and optional **Display name** of the subscription.
-1. Optionally, select **Allow tracing** to enable tracing for debugging and troubleshooting APIs. [Learn more](api-management-howto-api-inspector.md)
-
-    [!INCLUDE [api-management-tracing-alert](../../includes/api-management-tracing-alert.md)]
-
-    [!INCLUDE [api-management-availability-tracing-v2-tiers](../../includes/api-management-availability-tracing-v2-tiers.md)]
-
 1. Select a **Scope** of the subscription from the dropdown list. [Learn more](api-management-subscriptions.md#scope-of-subscriptions)
 1. Optionally, choose if the subscription should be associated with a **User** and whether to send a notification for use with the developer portal.
 1. Select **Create**.
diff --git a/articles/api-management/trace-policy.md b/articles/api-management/trace-policy.md
@@ -15,7 +15,7 @@ ms.author: danlep
 
 The `trace` policy adds a custom trace into the request tracing output in the test console, Application Insights telemetries, and/or resource logs.
 
--   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.
+-   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.
 -   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).
 -   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).
 -   The policy is not affected by Application Insights sampling. All invocations of the policy will be logged.
diff --git a/articles/api-management/visual-studio-code-tutorial.md b/articles/api-management/visual-studio-code-tutorial.md
@@ -107,7 +107,6 @@ You need a subscription key for your API Management instance to test the importe
 1. In the Explorer pane, expand the **Operations** node under the *demo-conference-api* that you imported.
 1. Select an operation such as *GetSpeakers*, and then right-click the operation and select **Test Operation**.
 1. In the editor window, next to **Ocp-Apim-Subscription-Key**, replace `{{SubscriptionKey}}` with the subscription key that you copied.
-1. Next to `Ocp-Apim-Trace`, enter `false`. This setting disables request tracing.
 1. Select **Send request**.
 
 :::image type="content" source="media/visual-studio-code-tutorial/test-api.png" alt-text="Screenshot of sending API request from Visual Studio Code.":::
@@ -126,24 +125,7 @@ Notice the following details in the response:
 
 Optionally, you can get detailed request tracing information to help you debug and troubleshoot the API.
 
-To trace request processing, first enable the **Allow tracing** setting for the subscription used to debug your API. For steps to enable this setting using the portal, see [Verify allow tracing setting](api-management-howto-api-inspector.md#verify-allow-tracing-setting). To limit unintended disclosure of sensitive information, tracing is allowed for only 1 hour.
-
-After allowing tracing with your subscription, follow these steps:
-
-1. In the Explorer pane, expand the **Operations** node under the *demo-conference-api* that you imported.
-1. Select an operation such as *GetSpeakers*, and then right-click the operation and select **Test Operation**.
-1. In the editor window, next to **Ocp-Apim-Subscription-Key**, replace `{{SubscriptionKey}}` with the subscription key that you want to use.
-1. Next to `Ocp-Apim-Trace`, enter `true`. This setting enables tracing for this request.
-1. Select **Send request**.
-
-When the request succeeds, the backend response includes an **Ocp-APIM-Trace-Location** header.
-
-:::image type="content" source="media/visual-studio-code-tutorial/test-api-tracing.png" alt-text="Screenshot of tracing location in the API test response in Visual Studio Code.":::
-
-Select the link next to **Ocp-APIM-Trace-Location** to see Inbound, Backend, and Outbound trace information. The trace information helps you determine where problems occur after the request is made.
-
-> [!TIP]
-> When you test API operations, the API Management extension allows optional [policy debugging](api-management-debug-policies.md) (available only in the Developer service tier).
+For steps to enable tracing for an API, see [Enable tracing for an API](api-management-howto-api-inspector.md#enable-tracing-for-an-api). To limit unintended disclosure of sensitive information, tracing by default is allowed for only 1 hour.
 
 ## Clean up resources
 
diff --git a/includes/api-management-availability-tracing-v2-tiers.md b/includes/api-management-availability-tracing-v2-tiers.md
@@ -7,4 +7,4 @@ ms.author: danlep
 ---
 
 > [!NOTE]
-> Currently, API request tracing isn't supported in the Basic v2 and Standard v2 tiers. 
+> Currently, tracing of API requests isn't supported in the Basic v2 and Standard v2 tiers. 
diff --git a/includes/api-management-tracing-alert.md b/includes/api-management-tracing-alert.md
@@ -2,10 +2,10 @@
 author: dlepow
 ms.service: api-management
 ms.topic: include
-ms.date: 08/03/2022
+ms.date: 05/05/2024
 ms.author: danlep
 ---
-> [!WARNING]
-> * Only allow tracing on subscriptions intended for debugging purposes. Sharing subscription keys with tracing allowed with unauthorized users could lead to disclosure of sensitive information contained in tracing logs such as keys, access tokens, passwords, internal hostnames, and IP addresses.
-> * In the test console, API Management automatically disables tracing 1 hour after it's enabled on a subscription.
-
+> [!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.
