Merge pull request #268602 from EdB-MSFT/rest-activity-wildcards

separated activity log  to new article. added content about empty res…

Author: JamesJBarnett

articles/azure-monitor/essentials/data-platform-metrics.md

@@ -4,7 +4,7 @@ description: Learn about metrics in Azure Monitor, which are lightweight monitor
 author: bwren
 ms.reviewer: priyamishra
 ms.topic: conceptual
-ms.date: 04/25/2023
+ms.date:   03/10/2024
 ms.author: bwren
 ---
 
@@ -46,12 +46,15 @@ The differences between each of the metrics are summarized in the following tabl
 
 Azure Monitor collects metrics from the following sources. After these metrics are collected in the Azure Monitor metric database, they can be evaluated together regardless of their source:
 
-- **Azure resources**: Platform metrics are created by Azure resources and give you visibility into their health and performance. Each type of resource creates a [distinct set of metrics](./metrics-supported.md) without any configuration required. Platform metrics are collected from Azure resources at one-minute frequency unless specified otherwise in the metric's definition.
+- **Azure resources**: Platform metrics are created by Azure resources and give you visibility into their health and performance. Each type of resource creates a [distinct set of metrics](./metrics-supported.md) without any configuration required. Platform metrics are collected from Azure resources at one-minute frequency unless specified otherwise in the metric's definition. 
 - **Applications**: Application Insights creates metrics for your monitored applications to help you detect performance issues and track trends in how your application is being used. Values include _Server response time_ and _Browser exceptions_.
 - **Virtual machine agents**: Metrics are collected from the guest operating system of a virtual machine. You can enable guest OS metrics for Windows virtual machines by using the [Azure Monitor Agent](/azure/azure-monitor/agents/agents-overview). Azure Monitor Agent replaces the legacy agents - [Windows diagnostic extension](../agents/diagnostics-extension-overview.md) and the [InfluxData Telegraf agent](https://www.influxdata.com/time-series-platform/telegraf/) for Linux virtual machines.
 - **Custom metrics**: You can define metrics in addition to the standard metrics that are automatically available. You can [define custom metrics in your application](../app/api-custom-events-metrics.md) that's monitored by Application Insights. You can also create custom metrics for an Azure service by using the [custom metrics API](./metrics-store-custom-rest-api.md).
 - **Kubernetes clusters**: Kubernetes clusters typically send metric data to a local Prometheus server that you must maintain. [Azure Monitor managed service for Prometheus ](prometheus-metrics-overview.md) provides a managed service that collects metrics from Kubernetes clusters and store them in Azure Monitor Metrics.
 
+> [!NOTE]
+> Metrics collected from different sources and by different methods may be aggregated differently. For example, platform metrics are pre-aggregated and stored in a time-series database, while Prometheus metrics are stored as raw data.Resource metrics may also have a different latency than other metrics. This can lead to differences in metric values for a specific sample time. Over time when latency ceases to be an issue, and when analyzing the metrics at the same time granularity, these differences disappear.
+
 ## REST API
 
 Azure Monitor provides REST APIs that allow you to get data in and out of Azure Monitor Metrics.

articles/azure-monitor/essentials/migrate-to-batch-api.md

@@ -4,17 +4,18 @@ description: How to migrate from the metrics API to the getBatch API
 author: EdB-MSFT
 services: azure-monitor
 ms.topic: how-to
-ms.date: 05/07/2023
+ms.date: 03/11/2024
 ms.author: edbaynash
+ms.reviewer: priyamishra
 
 # Customer intent: As a customer, I want to understand how to migrate from the metrics API to the getBatch API
 ---
 # How to migrate from the metrics API to the getBatch API
 
-Heavy use of the [metrics API](/rest/api/monitor/metrics/list?tabs=HTTP) can result in throttling or performance problems. Migrating to the [metrics:getBatch](/rest/api/monitor/metrics-batch/batch?tabs=HTTP) API allows you to query multiple resources in a single REST request. The two APIs share a common set of query parameter and response formats that make migration easy.
+Heavy use of the [metrics API](/rest/api/monitor/metrics/list?tabs=HTTP) can result in throttling or performance problems. Migrating to the [`metrics:getBatch`](/rest/api/monitor/metrics-batch/batch?tabs=HTTP) API allows you to query multiple resources in a single REST request. The two APIs share a common set of query parameter and response formats that make migration easy.
 
 ## Request format 
- The metrics:getBatch API request has the following format:
+ The `metrics:getBatch` API request has the following format:
  ```http
 POST /subscriptions/<subscriptionId>/metrics:getBatch?metricNamespace=<resource type namespace>&api-version=2023-10-01
 Host: <region>.metrics.monitor.azure.com
@@ -41,7 +42,7 @@ Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb...TaXzf6tmC4jhog
 
 ## Batching restrictions
 
-Consider the following restrictions on which resources can be batched together when deciding if the metrics:getBatch API is the correct choice for your scenario.
+Consider the following restrictions on which resources can be batched together when deciding if the `metrics:getBatch` API is the correct choice for your scenario.
 
 - All resources in a batch must be in the same subscription.
 - All resources in a batch must be in the same Azure region.
@@ -69,16 +70,16 @@ GET https://management.azure.com/subscriptions/12345678-1234-1234-1234-123456789
  Replace  `management.azure.com` with a regional endpoint for the Azure Monitor Metrics data plane using the following format: `<region>.metrics.monitor.azure.com` where `region` is region of the resources you're requesting metrics for.  For the example, if the resources are in westus2, the hostname is  `westus2.metrics.monitor.azure.com`.
 
 1. Change the API name and path.  
- The metrics:getBatch API is a subscription level POST API. The resources for which the metrics are requested, are specified in the request body rather than in the URL path.  
+ The `metrics:getBatch` API is a subscription level POST API. The resources for which the metrics are requested, are specified in the request body rather than in the URL path.  
  Change the url path as follows:  
     from `/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics`  
      to `/subscriptions/12345678-1234-1234-1234-123456789abc/metrics:getBatch`
 
-1. The `metricNamespace` query param is required for metrics:getBatch. For Azure standard metrics, the namespace name is usually the resource type of the resources you've specified. To check the namespace value to use, see the [metrics namespaces API](/rest/api/monitor/metric-namespaces/list?tabs=HTTP)
+1. The `metricNamespace` query param is required for metrics:getBatch. For Azure standard metrics, the namespace name is usually the resource type of the resources you specified. To check the namespace value to use, see the [metrics namespaces API](/rest/api/monitor/metric-namespaces/list?tabs=HTTP)
 1. Switch from using the `timespan` query param to using `starttime` and `endtime`.  For example, `?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z` becomes `?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z`.
 1. Update the api-version query parameter as follows: `&api-version=2023-10-01`
-1. The filter query param isn't prefixed with a `$` in the metrics:getBatch API. Change the query param from `$filter=` to `filter=`.
-1.  The metrics:getBatch API is a POST call with a body that contains a comma-separated list of resourceIds in the following format:
+1. The filter query param isn't prefixed with a `$` in the `metrics:getBatch` API. Change the query param from `$filter=` to `filter=`.
+1.  The `metrics:getBatch` API is a POST call with a body that contains a comma-separated list of resourceIds in the following format:
     For example:
     ```json
         {
@@ -123,7 +124,7 @@ The following example shows the converted batch request.
 
 ## Response Format
 
-The response format of the metrics:getBatch API encapsulates a list of individual metrics call responses in the following format:
+The response format of the `metrics:getBatch` API encapsulates a list of individual metrics call responses in the following format:
 
 ```json
 {
@@ -133,7 +134,7 @@ The response format of the metrics:getBatch API encapsulates a list of individua
 }
 ```
 
-A `resourceid` property has been added to each resources' metrics list in the metrics:getBatch API response.
+A `resourceid` property was added to each resources' metrics list in the `metrics:getBatch` API response.
 
  The following show sample response formats.
 
@@ -587,7 +588,7 @@ A `resourceid` property has been added to each resources' metrics list in the me
 
 ## Error response changes
 
-In the metrics:getBatch error response, the error content is wrapped inside a top level "error" property on the response. For example,
+In the `metrics:getBatch` error response, the error content is wrapped inside a top level "error" property on the response. For example,
 
 + Metrics API error response
 
@@ -611,26 +612,30 @@ In the metrics:getBatch error response, the error content is wrapped inside a to
 
 ## Troubleshooting
 
-+ No returned data can be due to the wrong region being specified.  
-    The batch API verifies that all of the resource IDs specified belong to the same subscriptionId and resource type. The batch API doesn't verify that all of the specified resource IDs are in the same region specified in the hostname. The only indicator that the region may be wrong for a given resource is getting empty time series data for all that resource.
-    for example,`"timeseries": [],`
-
++ Empty time series returned `"timeseries": []` 
+    - An empty time series is returned when no data is available for the specified time range and filter. The most common cause is specifying a time range that doesn't contain any data. For example, if the time range is set to a future date.
+    - Another common cause is specifying a filter that doesn't match any resources. For example, if the filter specifies a dimension value that doesn't exist on any resources in the subscription and region combination, `"timeseries": []` is returned. 
+    
++  Wildcard filters  
+    Using a wildcard filter such as `Microsoft.ResourceId eq '*'` causes the API to return a time series for every resourceId in the subscription and region. If the subscription and region combination contains no resources, an empty time series is returned. The same query without the wildcard filter would return a single time series, aggregating the requested metric over the requested dimensions, for example subscription and region. If there are no resources in the subscription and region combination, the API returns a single time series with a single data point of `0`.
+ 
+ 
 + Custom metrics aren't currently supported.  
-    The metrics:getBatch API doesn't support querying custom metrics, or queries where the metric namespace name isn't a resource type. This is the case for VM Guest OS metrics that use the namespace "azure.vm.windows.guestmetrics" or "azure.vm.linux.guestmetrics".
+    The `metrics:getBatch` API doesn't support querying custom metrics, or queries where the metric namespace name isn't a resource type. This is the case for VM Guest OS metrics that use the namespace "azure.vm.windows.guestmetrics" or "azure.vm.linux.guestmetrics".
 
 + The top parameter applies per resource ID specified.  
 How the top parameter works in the context of the batch API can be a little confusing. Rather than enforcing a limit on the total time series returned by the entire call, it rather enforces the total time series returned *per metric per resource ID*. If you have a batch query with many '*' filters specified, two metrics, and four resource IDs with a top of 5. The maximum possible time series returned by that query is 40, that is 2x4x5 time series.
 
 ### 401 authorization errors
 
-The individual metrics API requires a user have the [Monitoring Reader](/azure/role-based-access-control/built-in-roles#monitoring-reader) permission on the resource being queried. Because the metrics:getBatch API is a subscription level API, users must have the Monitoring Reader permission for the queried subscription to use the batch API. Even if users have Monitoring Reader on all the resources being queried in the batch API, the request fails if the user doesn't have Monitoring Reader on the subscription itself.
+The individual metrics API requires a user have the [Monitoring Reader](/azure/role-based-access-control/built-in-roles#monitoring-reader) permission on the resource being queried. Because the `metrics:getBatch` API is a subscription level API, users must have the Monitoring Reader permission for the queried subscription to use the batch API. Even if users have Monitoring Reader on all the resources being queried in the batch API, the request fails if the user doesn't have Monitoring Reader on the subscription itself.
 
 ### 529 throttling errors
 
 While the data plane batch API is designed to help mitigate throttling problems, 529 error codes can still occur which indicates that the metrics backend is currently throttling some customers. The recommended action is to implement an exponential backoff retry scheme.
 
 ## Paging 
-Paging is not supported by the metrics:getBatch API. The most common use-case for this API is frequently calling every few minutes for the same metrics and resources for the latest timeframe. Low latency is an important consideration so many customers parallelize their queries as much as possible. Paging forces customers into a sequential calling pattern that introduces additional query latency. In scenarios where requests return volumes of metric data where paging would be beneficial, it's recommended to split the query into multiple parallel queries.
+Paging isn't supported by the metrics: getBatch API. The most common use-case for this API is frequently calling every few minutes for the same metrics and resources for the latest timeframe. Low latency is an important consideration so many customers parallelize their queries as much as possible. Paging forces customers into a sequential calling pattern that introduces additional query latency. In scenarios where requests return volumes of metric data where paging would be beneficial, it's recommended to split the query into multiple parallel queries.
 
 ## Billing
-Yes all metrics data plane and batching calls are billed. For more information, see the **Azure Monitor native metrics** section in [Basic Log Search Queries](https://azure.microsoft.com/pricing/details/monitor/#pricing)
+Yes all metrics data plane and batching calls are billed. For more information, see the **Azure Monitor native metrics** section in [Basic Log Search Queries](https://azure.microsoft.com/pricing/details/monitor/#pricing).

articles/azure-monitor/essentials/rest-activity-log.md

@@ -0,0 +1,71 @@
+---
+title: Retrieve activity log data using Azure monitor REST API
+description: How to retrieve activity log data using Azure monitor REST API.
+author: EdB-MSFT
+ms.topic: conceptual
+ms.date: 03/10/2024
+ms.reviewer: priyamishra
+
+# customer intent: As a developer, I want to learn how to retrieve activity log data using Azure monitor REST API.
+---
+
+# Retrieve activity log data using Azure monitor REST API
+
+The Azure Activity Log is a log that provides insight into operations performed on resources in your subscription. Operations include create, update, delete, and other actions taken on resources. The Activity Log is a platform-wide log and isn't limited to a particular service. This article explains how to retrieve activity log data using the Azure Monitor REST API. For more information about the activity log, see [Azure Activity Log event schema](/azure/azure-monitor/essentials/activity-log-schema).
+
+
+## Authentication
+
+To retrieve resource logs, you must authenticate with Microsoft Entra. For more information, see [Azure monitoring REST API walkthrough](/azure/azure-monitor/essentials/rest-api-walkthrough?tabs=powershell#authenticate-azure-monitor-requests).
+
+## Retrieve activity log data
+
+Use the Azure Monitor REST API to query [activity log](/rest/api/monitor/activitylogs) data. 
+
+The following request format is used to request activity log data.
+
+```curl 
+GET /subscriptions/<subscriptionId>/providers/Microsoft.Insights/eventtypes/management/values \
+?api-version=2015-04-01 \
+&$filter=<filter> \
+&$select=<select>
+host: management.azure.com
+authorization: Bearer <token>
+```
+
+### $filter
+`$filter` reduces the set of data collected. This argument is required and it also requires at least the start date/time.
+The `$filter` argument accepts the following patterns:
+- List events for a resource group: `$filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceGroupName eq <resourceGroupName>`.
+- List events for a specific resource: `$filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceUri eq <resourceURI>`.
+- List events for a subscription in a time range: `$filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z'`.
+- List events for a resource provider: `$filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceProvider eq <resourceProviderName>`.
+- List events for a correlation ID:` $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and correlationId eq '<correlationID>`.
+
+
+### $select
+`$select` fetches a specified list of properties for the returned events.
+The `$select` argument is a comma separated list of property names to be returned. 
+Valid values are: 
+`authorization`, `claims`, `correlationId`, `description`, `eventDataId`, `eventName`, `eventTimestamp`, `httpRequest`, `level`, `operationId`, `operationName`, `properties`, `resourceGroupName`, `resourceProviderName`, `resourceId`, `status`, `submissionTimestamp`, `subStatus`, and `subscriptionId`.
+
+The following sample requests use the Azure Monitor REST API to query an activity log.
+### Get activity logs with filter:
+
+The following example gets the activity logs for resource group `MSSupportGroup` between the dates `2023-03-21T20:00:00Z` and `2023-03-24T20:00:00Z`
+
+``` HTTP
+GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&$filter=eventTimestamp ge '2023-03-21T20:00:00Z' and eventTimestamp le '2023-03-24T20:00:00Z' and resourceGroupName eq 'MSSupportGroup'
+```
+### Get activity logs with filter and select:
+
+The following example gets the activity logs for resource group `MSSupportGroup`, between the dates `2023-03-21T20:00:00Z` and `2023-03-24T20:00:00Z`, returning the elements eventName, operationName, status, eventTimestamp, correlationId, submissionTimestamp, and level.
+
+```HTTP
+GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&$filter=eventTimestamp ge '2023-03-21T20:00:00Z' and eventTimestamp le '2023-03-24T20:00:00Z'and resourceGroupName eq 'MSSupportGroup'&$select=eventName,operationName,status,eventTimestamp,correlationId,submissionTimestamp,level
+```
+
+## Next steps
+[Stream Azure Monitor activity log data](/azure/azure-monitor/essentials/activity-log).
+[Azure Activity Log event schema](/azure/azure-monitor/essentials/activity-log-schema).
+