Merge pull request #222861 from EdB-MSFT/update-send-custom-metrics

Updated and refeshed how to send custom metrics

Author: BCS2022

articles/azure-monitor/essentials/media/metrics-store-custom-rest-api/Metrics.png

@@ -1,50 +1,81 @@
 ---
 title: Send metrics to the Azure Monitor metric database using REST API
 description: Send custom metrics for an Azure resource to the Azure Monitor metric store by using a REST API
-author: anirudhcavale
+author: EdB-MSFT
 services: azure-monitor
 ms.reviewer: priyamishra
 ms.topic: conceptual
-ms.date: 09/24/2018
-ms.author: ancav
+ms.date: 01/04/2023
+ms.author: edbaynash
 ---
 # Send custom metrics for an Azure resource to the Azure Monitor metric store by using a REST API
 
-This article shows you how to send custom metrics for Azure resources to the Azure Monitor metrics store via a REST API. After the metrics are in Azure Monitor, you can do all the things with them that you do with standard metrics. Examples are charting, alerting, and routing them to other external tools.  
+This article shows you how to send custom metrics for Azure resources to the Azure Monitor metrics store via a REST API. When the metrics are in Azure Monitor, you can do all the things with them that you do with standard metrics. For example, charting, alerting, and routing them to other external tools.  
 
 >[!NOTE]  
->The REST API only permits sending custom metrics for Azure resources. To send metrics for resources in different environments or on-premises, you can use [Application Insights](../app/api-custom-events-metrics.md).    
+>The REST API only permits sending custom metrics for Azure resources.  
+To send metrics for resources in other environments or on-premises, use [Application Insights](../app/api-custom-events-metrics.md).  
 
+## Create and authorize a service principal to emit metrics  
 
-## Create and authorize a service principal to emit metrics 
+A service principal is an application whose tokens can be used to authenticate and grant access to specific Azure resources using Azure Active Directory. This includes user-apps, services or automation tools.
 
-Create a service principal in your Azure Active Directory tenant by using the instructions found at [Create a service principal](../../active-directory/develop/howto-create-service-principal-portal.md). 
+1. [Register an application with Azure Active Directory](../logs/api/register-app-for-token.md) to create a service principal.
 
-Note the following while you go through this process: 
+1. Save the tenant ID, new client ID, and client secret value for your app to use when requesting a token.
 
-- You can enter any URL for the sign-in URL.  
-- Create a new client secret for this app.  
-- Save the key and the client ID for use in later steps.  
-
-Give the app created as part of step 1, Monitoring Metrics Publisher, permissions to the resource you wish to emit metrics against. If you plan to use the app to emit custom metrics against many resources, you can grant these permissions at the resource group or subscription level. 
+1. Give the app created as part of the previous step **Monitoring Metrics Publisher** permissions to the resource you wish to emit metrics against. If you plan to use the app to emit custom metrics against many resources, you can grant these permissions at the resource group or subscription level.  
+ 
+    On your resource's overview page, select **Access Control (IAM)**
+1. Select **Add**, then **Add role assignment** from the dropdown.
+    :::image type="content" source="./media/metrics-store-custom-rest-api/access-contol-add-role-assignment.png" alt-text="A screenshot showing the Access control(IAM) page for a virtual machine.":::
+1. Search for *Monitoring Metrics* in the search field.
+1. Select **Monitoring Metrics Publisher** from the list.
+1. Select **Members**.
+    :::image type="content" source="./media/metrics-store-custom-rest-api/add-role-assignment.png" alt-text="A screenshot showing the add role assignment page.":::
+
+1. Search for your app  in the **Select** field.
+1. Select your app from the list.
+1. Click **Select**.
+1. Select **Review + assign**.
+    :::image type="content" source="./media/metrics-store-custom-rest-api/select-members.png" alt-text="A screenshot showing the members tab of the role assignment page.":::
 
 ## Get an authorization token
-Open a command prompt and run the following command:
+
+Send the following request in the command prompt or using a client like Postman.
 
 ```shell
-curl -X POST https://login.microsoftonline.com/<yourtenantid>/oauth2/token -F "grant_type=client_credentials" -F "client_id=<insert clientId from earlier step>" -F "client_secret=<insert client secret from earlier step>" -F "resource=https://monitoring.azure.com/"
+curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
+-H 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'grant_type=client_credentials' \
+--data-urlencode 'client_id=<your apps client ID>' \
+--data-urlencode 'client_secret=<your apps client secret' \
+--data-urlencode 'resource=https://management.azure.com'
+```
+
+The response body appears as follows:  
+
+```JSON
+{
+    "token_type": "Bearer",
+    "expires_in": "86399",
+    "ext_expires_in": "86399",
+    "expires_on": "1672826207",
+    "not_before": "1672739507",
+    "resource": "https://monitoring.azure.com",
+    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
+}
 ```
-Save the access token from the response.
 
-![Access token](./media/metrics-store-custom-rest-api/accesstoken.png)
+Save the access token from the response for use in the following HTTP requests.
 
-## Emit the metric via the REST API 
+## Send a metric via the REST API
 
-1. Paste the following JSON into a file, and save it as **custommetric.json** on your local computer. Update the time parameter in the JSON file: 
+1. Paste the following JSON into a file, and save it as **custommetric.json** on your local computer. Update the time parameter so that it is within the last 20 minutes.  You can't put a metric into the store that's over 20 minutes old. The metric store is optimized for alerting and real-time charting.
 
-    ```json
+    ```JSON
     { 
-        "time": "2018-09-13T16:34:20", 
+        "time": "2023-01-03T11:00:20", 
         "data": { 
             "baseData": { 
                 "metric": "QueueDepth", 
@@ -68,48 +99,49 @@ Save the access token from the response.
             } 
         } 
     } 
-    ``` 
+    ```
 
-1. In your command prompt window, post the metric data: 
-   - **azureRegion**. Must match the deployment region of the resource you're emitting metrics for. 
-   - **resourceID**.  Resource ID of the Azure resource you're tracking the metric against.  
-   - **AccessToken**. Paste the token that you acquired previously.
+1. Submit the following HTTP POST request using the following variables:
+   - **location**: Deployment region of the resource you're emitting metrics for.
+   - **resourceId**:   Resource ID of the Azure resource you're tracking the metric against.  
+   - **accessToken**:  The authorization token acquired from the previous step.
+    
+    ```Shell
+    curl -X POST 'https://<location>.monitoring.azure.com/<resourceId>/metrics' \
+    -H 'Content-Type: application/json' \
+    -H 'Authorization: Bearer <accessToken>' \
+    -d @custommetric.json 
+    ```
 
-     ```Shell 
-     curl -X POST https://<azureRegion>.monitoring.azure.com/<resourceId>/metrics -H "Content-Type: application/json" -H "Authorization: Bearer <AccessToken>" -d @custommetric.json 
-     ```
 1. Change the timestamp and values in the JSON file. 
-1. Repeat the previous two steps a few times, so you have data for several minutes.
-
-## Troubleshooting 
-If you receive an error message with some part of the process, consider the following troubleshooting information:
+1. Repeat the previous two steps a number of times, to create data for several minutes.
 
-1. You can't issue metrics against a subscription or resource group as your Azure resource. 
-1. You can't put a metric into the store that's over 20 minutes old. The metric store is optimized for alerting and real-time charting. 
-2. The number of dimension names should match the values and vice versa. Check the values. 
-2. You might be emitting metrics against a region that doesn’t support custom metrics. See [supported regions](./metrics-custom-overview.md#supported-regions). 
+## Troubleshooting
 
+If you receive an error message with some part of the process, consider the following troubleshooting information:
 
+- If you can't issue metrics against a subscription or resource group, or resource, check that your application or Service Principal has the **Monitoring Metrics Publisher** role assigned in Access control (IAM).
+- Check that the number of dimension names matches the number values.
+- Check that you are not emitting metrics against a region that doesn’t support custom metrics. See [supported regions](./metrics-custom-overview.md#supported-regions).
 
-## View your metrics 
+## View your metrics
 
-1. Sign in to the Azure portal. 
+1. Sign in to the Azure portal.
 
-1. In the left-hand menu, select **Monitor**. 
+1. In the left-hand menu, select **Monitor**.
 
-1. On the **Monitor** page, select **Metrics**. 
+1. On the **Monitor** page, select **Metrics**.
 
-   ![Select Metrics](./media/metrics-store-custom-rest-api/metrics.png) 
+   ![Select Metrics](./media/metrics-store-custom-rest-api/metrics.png)
 
-1. Change the aggregation period to **Last 30 minutes**.  
+1. Change the aggregation period to **Last hour**.  
 
-1. In the **resource** drop-down menu, select the resource you emitted the metric against.  
+1. In the **Scope** drop-down menu, select the resource you send the metric for.  
 
-1. In the **namespaces** drop-down menu, select **QueueProcessing**. 
+1. In the **Metric namespace** drop-down menu, select **QueueProcessing**.
 
-1. In the **metrics** drop-down menu, select **QueueDepth**.  
+1. In the **Metric** drop-down menu, select **QueueDepth**.  
 
- 
 ## Next steps
-- Learn more about [custom metrics](./metrics-custom-overview.md).
 
+- Learn more about [custom metrics](./metrics-custom-overview.md).

articles/azure-monitor/essentials/media/metrics-store-custom-rest-api/access-contol-add-role-assignment.png

@@ -62,6 +62,35 @@ For example,
 
 To access the  API, you need to register a client app with Azure Active Directory and request a token.
 1. [Register an app in Azure Active Directory](./register-app-for-token.md).
+
+1. On the app's overview page, select **API permissions**  
+1. Select **Add a permission**
+1. In the **APIs my organization uses** tab search for *log analytics* and select **Log Analytics API** from the list.  
+:::image type="content" source="../media/api-register-app/request-api-permissions.png" alt-text="A screenshot showing the Request API permissions page.":::
+
+1. Select **Delegated permissions**
+1. Check the checkbox for **Data.Read**
+1. Select **Add permissions**
+:::image type="content" source="../media/api-register-app/add-requested-permissions.png" alt-text="A screenshot showing the continuation of the Request API permissions page.":::  
+
+Now that your app is registered and has permissions to use the API, grant your app access to your Log Analytics Workspace.
+
+1. From your Log analytics Workspace overview page, select **Access control (IAM)**.
+1. Select **Add role assignment**.
+
+    :::image type="content" source="../media/api-register-app/workspace-access-control.png" alt-text="A screenshot showing the access control page for a log analytics workspace.":::
+
+1. Select the **Reader** role then select **Members**
+    
+    :::image type="content" source="../media/api-register-app/add-role-assignment.png" alt-text="A screenshot showing the add role assignment page for a log analytics workspace.":::
+
+1. In the Members tab, select **Select members**
+1. Enter the name of your app in the **Select** field.
+1. Choose your app and select **Select**
+1. Select **Review and assign**
+     
+    :::image type="content" source="../media/api-register-app/select-members.png" alt-text="A screenshot showing the select members blade on the role assignment page for a log analytics workspace.":::
+
 1. After completing the Active Directory setup and workspace permissions, request an authorization token.
 
 ## Request an Authorization Token

articles/azure-monitor/essentials/media/metrics-store-custom-rest-api/add-role-assignment.png

@@ -1,15 +1,15 @@
 ---
-title: Register an App for API Access
-description: How to register an app and assign a role so it can access a log analytics workspace using the API
+title: Register an App to request authorization tokens and work with APIs
+description: How to register an app and assign a role so it can access request a token and work with APIs
 author: EdB-MSFT
 ms.author: edbaynash
-ms.date: 11/18/2021
+ms.date: 01/04/2023
 ms.topic: article
 ---
 
-# Register an App to work with Log Analytics APIs
+# Register an App to request authorization tokens and work with APIs
 
-To access the log analytics API, you can generate a token based on a client ID and secret. This article shows you how to register a client app and assign permissions to access a Log Analytics Workspace.
+To access Azure REST APIs such as the Log analytics API, or to send custom metrics, you can generate an authorization token based on a client ID and secret. The token is then passed in your REST API request. This article shows you how to register a client app and create a client secret so that you can generate a token.
 
 ## Register an App
 
@@ -21,15 +21,6 @@ To access the log analytics API, you can generate a token based on a client ID a
 1. Select **New registration**
 1. On the Register an application page, enter a **Name** for the application. 
 1. Select **Register**
-1. On the app's overview page, select **API permissions**  
-1. Select **Add a permission**
-1. In the **APIs my organization uses** tab search for *log analytics* and select **Log Analytics API** from the list.  
-:::image type="content" source="../media/api-register-app/request-api-permissions.png" alt-text="A screenshot showing the Request API permissions page.":::
-
-1. Select **Delegated permissions**
-1. Check the checkbox for **Data.Read**
-1. Select **Add permissions**
-:::image type="content" source="../media/api-register-app/add-requested-permissions.png" alt-text="A screenshot showing the continuation of the Request API permissions page.":::  
 
 1. On the app's overview page, select **Certificates and Secrets**
 1. Note the **Application (client) ID**. It's used in the HTTP request for a token.
@@ -39,34 +30,26 @@ To access the log analytics API, you can generate a token based on a client ID a
 1. Enter a **Description** and select **Add**
  :::image type="content" source="../media/api-register-app/add-a-client-secret.png" alt-text="A screenshot showing the Add client secret page.":::
 
-1. Copy and save the client secret **Value**. 
+1. Copy and save the client secret **Value**.  
 
    > [!NOTE]
    > Client secret values can only be viewed immediately after creation. Be sure to save the secret before leaving the page.  
 
      :::image type="content" source="../media/api-register-app/client-secret.png" alt-text="A screenshot showing the client secrets page.":::
 
-## Grant your app access to a Log Analytics Workspace
-
-1. From your Log analytics Workspace overview page, select **Access control (IAM)**.
-1. Select **Add role assignment**.
 
-    :::image type="content" source="../media/api-register-app/workspace-access-control.png" alt-text="A screenshot showing the access control page for a log analytics workspace.":::
+## Next steps
 
-1. Select the **Reader** role then select **Members**
-    
-    :::image type="content" source="../media/api-register-app/add-role-assignment.png" alt-text="A screenshot showing the add role assignment page for a log analytics workspace.":::
+Before you can generate a token using your app, client ID, and secret, assign the app to a role using Access control (IAM) for resource that you want to access.
+The role will depend on the resource type and the API that you want to use.  
+For example,
+- To grant your app read from a Log Analytics Workspace, add your app as a member to the **Reader** role using Access control (IAM) for your Log Analytics Workspace. For more information, see [Access the API](./access-api.md)
 
-1. In the Members tab, select **Select members**
-1. Enter the name of your app in the **Select** field.
-1. Choose your app and select **Select**
-1. Select **Review and assign**
-     
-    :::image type="content" source="../media/api-register-app/select-members.png" alt-text="A screenshot showing the select members blade on the role assignment page for a log analytics workspace.":::
+- To grant access to send custom metrics for a resource,  add your app as a member to the **Monitoring Metrics Publisher** role using Access control (IAM) for your resource. For more information, see [ Send metrics to the Azure Monitor metric database using REST API](../../essentials/metrics-store-custom-rest-api.md)
 
-## Next steps
+For more information see [Assign Azure roles using the Azure portal](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal)  
 
-You can use your client ID and client secret to generate a bearer token to access the Log Analytics API. For more information, see [Access the API](./access-api.md)
+Once you have assigned a role you can use your app, client ID, and client secret to generate a bearer token to access the REST API.
 
 > [!NOTE]
 > When using Azure AD authentication, it may take up to 60 minutes for the Azure Application Insights REST API to recognize new role-based access control (RBAC) permissions. While permissions are propagating, REST API calls may fail with error code 403.