Merge pull request #233348 from dlepow/emit

[APIM] Update emit custom metrics details

Author: American-Dipper

articles/api-management/api-management-howto-app-insights.md

@@ -7,9 +7,10 @@ author: dlepow
 
 ms.service: api-management
 ms.tgt_pltfrm: na
-ms.topic: article
-ms.date: 10/27/2021
+ms.topic: how-to
+ms.date: 04/03/2023
 ms.author: danlep
+ms.custom: engagement-fy23
 
 ---
 
@@ -55,9 +56,14 @@ To use Application Insights, [create an instance of the Application Insights ser
 
 ## Enable Application Insights logging for your API
 
+Use the following steps to enable Application Insights logging for an API. You can also enable Application Insights logging for all APIs.
+
 1. Navigate to your **Azure API Management service instance** in the **Azure portal**.
 1. Select **APIs** from the menu on the left.
 1. Click on your API, in this case **Demo Conference API**. If configured, select a version.
+
+   > [!TIP]
+   > To enable logging for all APIs, select **All APIs**.
 1. Go to the **Settings** tab from the top bar.
 1. Scroll down to the **Diagnostics Logs** section.  
     :::image type="content" source="media/api-management-howto-app-insights/apim-app-insights-api-1.png" alt-text="App Insights logger":::
@@ -66,8 +72,8 @@ To use Application Insights, [create an instance of the Application Insights ser
 1. Input **100** as **Sampling (%)** and select the **Always log errors** checkbox.
 1. Leave the rest of the settings as is. For details about the settings, see [Diagnostic logs settings reference](diagnostic-logs-reference.md).
 
-    > [!WARNING]
-    > Overriding the default **Number of payload bytes to log** value **0** may significantly decrease the performance of your APIs.
+   > [!WARNING]
+   > Overriding the default **Number of payload bytes to log** value **0** may significantly decrease the performance of your APIs.
 
 1. Select **Save**.
 1. Behind the scenes, a [Diagnostic](/rest/api/apimanagement/current-ga/diagnostic/create-or-update) entity named `applicationinsights` is created at the API level.
@@ -83,7 +89,7 @@ You can specify loggers on different levels:
 + A logger for all APIs
 
 Specifying *both*:
-- By default, the single API logger (more granular level) will override the one for all APIs.
+- By default, the single API logger (more granular level) overrides the one for all APIs.
 - If the loggers configured at the two levels are different, and you need both loggers to receive telemetry (multiplexing), please contact Microsoft Support. 
 
 ## What data is added to Application Insights
@@ -97,15 +103,41 @@ Application Insights receives:
 | *Exception* | For every failed request: <ul><li>Failed because of a closed client connection</li><li>Triggered an *on-error* section of the API policies</li><li>Has a response HTTP status code matching 4xx or 5xx</li></ul> |
 | *Trace* | If you configure a [trace](trace-policy.md) policy. <br /> The `severity` setting in the `trace` policy must be equal to or greater than the `verbosity` setting in the Application Insights logging. |
 
-### Emit custom metrics
-You can emit custom metrics by configuring the [`emit-metric`](emit-metric-policy.md) policy. 
+> [!NOTE]
+> See [Application Insights limits](../azure-monitor/service-limits.md#application-insights) for information about the maximum size and number of metrics and events per Application Insights instance.
 
-To make Application Insights pre-aggregated metrics available in API Management, you'll need to manually enable custom metrics in the service.
-1. Use the [`emit-metric`](emit-metric-policy.md) policy with the [Create or Update API](/rest/api/apimanagement/current-ga/api-diagnostic/create-or-update).
-1. Add `"metrics":true` to the payload, along with any other properties.
+## Emit custom metrics
+You can emit [custom metrics](../azure-monitor/essentials/metrics-custom-overview.md) to Application Insights from your API Management instance. API Management emits custom metrics using the [emit-metric](emit-metric-policy.md) policy.
 
 > [!NOTE]
-> See [Application Insights limits](../azure-monitor/service-limits.md#application-insights) for information about the maximum size and number of metrics and events per Application Insights instance.
+> Custom metrics are a preview feature of Azure Monitor and subject to limitations.
+
+To emit custom metrics, perform the following configuration steps. 
+
+1. Enable **Custom metrics (Preview)** with custom dimensions in your Application Insights instance. 
+
+    1. Navigate to your Application Insights instance in the portal.
+    1. In the left menu, select **Usage and estimated costs**.
+    1. Select **Custom metrics (Preview)** > **With dimensions**.
+    1. Select **OK**. 
+
+1. Add the `"metrics": true` property to the `applicationInsights` diagnostic entity that's configured in API Management. Currently you must add this property using the API Management [Diagnostic - Create or Update](/rest/api/apimanagement/current-ga/diagnostic/create-or-update) REST API. For example:
+
+    ```http
+    PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights
+
+    {
+        [...]
+        {
+        "properties": {
+            "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
+            "metrics": true
+            [...]
+        }
+    }
+    ```
+1. Ensure that the Application Insights logger is configured at the scope you intend to emit custom metrics (either all APIs, or a single API). For more information, see [Enable Application Insights logging for your API](#enable-application-insights-logging-for-your-api), earlier in this article.
+1. Configure the `emit-metric` policy at a scope where Application Insights logging is configured (either all APIs, or a single API) and is enabled for custom metrics. For policy details, see the [`emit-metric`](emit-metric-policy.md) policy reference.
 
 ## Performance implications and log sampling