[Monitor Metrics] Add samples (#42242)

pvaneck · Copilot · web-flow · commit 011a618e8b61 · 2025-07-28T13:29:33.000-07:00
Signed-off-by: Paul Van Eck &lt;paulvaneck@microsoft.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/sdk/monitor/azure-monitor-querymetrics/CHANGELOG.md b/sdk/monitor/azure-monitor-querymetrics/CHANGELOG.md
@@ -1,13 +1,25 @@
 # Release History
 
-## 1.0.0 (Unreleased)
+## 1.0.0 (2025-07-28)
 
 ### Features Added
 
-- Initial release. This version includes the core functionality for querying metrics from Azure Monitor using the `MetricsClient`, which was originally introduced in the `azure-monitor-query` package.
+- **Initial release** of `azure-monitor-querymetrics` package with core Azure Monitor metrics querying functionality.
+- Includes the `MetricsClient` for querying metrics from Azure Monitor resources.
 
-### Breaking Changes
+**Migration from azure-monitor-query**
 
-### Bugs Fixed
+This package extracts the metrics functionality from the `azure-monitor-query` package to provide a focused solution for metrics querying.
 
-### Other Changes
+**For existing users of `MetricsClient`:**
+- Migration is straightforward - only import paths need to be updated.
+- The API surface remains unchanged.
+- **Before:** `from azure.monitor.query import MetricsClient`
+- **After:** `from azure.monitor.querymetrics import MetricsClient`
+
+**For users of `MetricsQueryClient`:**
+- This functionality is **not included** in this package.
+- **Recommended alternative:** Use `MonitorManagementClient` from the `azure-mgmt-monitor` package.
+- The management client provides comprehensive Azure Monitor resource management capabilities.
+
+For more details, see the [migration guide](https://aka.ms/azsdk/python/monitor/query/migration).
diff --git a/sdk/monitor/azure-monitor-querymetrics/README.md b/sdk/monitor/azure-monitor-querymetrics/README.md
@@ -1,14 +1,19 @@
 # Azure Monitor Query Metrics client library for Python
 
-The Azure Monitor Query Metrics client library is used to execute read-only queries against [Azure Monitor][azure_monitor_overview]'s metrics data platform:
+The Azure Monitor Query Metrics client library enables you to perform read-only queries against [Azure Monitor][azure_monitor_overview]'s metrics data platform. It is designed for retrieving numerical metrics from Azure resources, supporting scenarios such as monitoring, alerting, and troubleshooting.
 
-- [Metrics](https://learn.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics) - Collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics are lightweight and capable of supporting near real-time scenarios, making them useful for alerting and fast detection of issues.
+- [Metrics](https://learn.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics): Numeric data collected from resources at regular intervals, stored as time series. Metrics provide insights into resource health and performance, and are optimized for near real-time analysis.
+
+This library interacts with the Azure Monitor Metrics Data Plane API, allowing you to query metrics for multiple resources in a single request. For details on batch querying, see [Batch API migration guide](https://learn.microsoft.com/azure/azure-monitor/metrics/migrate-to-batch-api?tabs=individual-response).
 
 **Resources:**
 
-<!-- TODO: Add PyPI, Conda, Ref Docs, Samples links-->
+<!-- TODO: Add Conda-->
 - [Source code][source]
+- [Package (PyPI)][package]
+- [API reference documentation][python-querymetrics-ref-docs]
 - [Service documentation][azure_monitor_overview]
+- [Samples][samples]
 - [Change log][changelog]
 
 ## Getting started
@@ -238,8 +243,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [azure_subscription]: https://azure.microsoft.com/free/python/
 [changelog]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-querymetrics/CHANGELOG.md
 [metric_namespaces]: https://learn.microsoft.com/azure/azure-monitor/reference/supported-metrics/metrics-index#supported-metrics-and-log-categories-by-resource-type
+[package]: https://aka.ms/azsdk-python-monitor-querymetrics-pypi
 [pip]: https://pypi.org/project/pip/
 [python_logging]: https://docs.python.org/3/library/logging.html
+[python-querymetrics-ref-docs]: https://aka.ms/azsdk/python/querymetrics/docs
 [samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-querymetrics/samples
 [source]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/
 [troubleshooting_guide]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/TROUBLESHOOTING.md
diff --git a/sdk/monitor/azure-monitor-querymetrics/TROUBLESHOOTING.md b/sdk/monitor/azure-monitor-querymetrics/TROUBLESHOOTING.md
@@ -48,7 +48,7 @@ client.query_workspace(logging_enable=True)
 
 ### Authentication errors
 
-Azure Monitor Query Metrics supports Azure Active Directory authentication. The MetricsClient has methods to set the `credential`. To provide a valid credential, you can use
+Azure Monitor Query Metrics supports Microsoft Entra ID authentication. The MetricsClient has methods to set the `credential`. To provide a valid credential, you can use
 `azure-identity` dependency. For more details on getting started, refer to
 the [README](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/monitor/azure-monitor-querymetrics#create-the-client)
 of Azure Monitor Query Metrics library. You can also refer to
diff --git a/sdk/monitor/azure-monitor-querymetrics/azure/monitor/querymetrics/_patch.py b/sdk/monitor/azure-monitor-querymetrics/azure/monitor/querymetrics/_patch.py
@@ -51,6 +51,24 @@ class MetricsClient(GeneratedClient):
     :keyword api_version: The API version to use for this operation. Default value is "2024-02-01".
      Note that overriding this default value may result in unsupported behavior.
     :paramtype api_version: str
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_metrics_client]
+            :end-before: [END create_metrics_client]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsClient with a credential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_metrics_client_sovereign_cloud]
+            :end-before: [END create_metrics_client_sovereign_cloud]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, endpoint: str, credential: "TokenCredential", **kwargs: Any) -> None:
@@ -140,6 +158,14 @@ def query_resources(
         :return: A list of MetricsQueryResult objects.
         :rtype: list[~azure.monitor.querymetrics.MetricsQueryResult]
         :raises ~azure.core.exceptions.HttpResponseError:
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_metrics_query.py
+                :start-after: [START send_metrics_batch_query]
+                :end-before: [END send_metrics_batch_query]
+                :language: python
+                :caption: Get a response for a batch metrics query.
         """
         if not resource_ids:
             raise ValueError("'resource_ids' must be provided and must not be empty.")
diff --git a/sdk/monitor/azure-monitor-querymetrics/azure/monitor/querymetrics/aio/_patch.py b/sdk/monitor/azure-monitor-querymetrics/azure/monitor/querymetrics/aio/_patch.py
@@ -46,6 +46,24 @@ class MetricsClient(GeneratedClient):
     :keyword api_version: The API version to use for this operation. Default value is "2024-02-01".
      Note that overriding this default value may result in unsupported behavior.
     :paramtype api_version: str
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication_async.py
+            :start-after: [START create_metrics_client_async]
+            :end-before: [END create_metrics_client_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the asynchronous MetricsClient with a credential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication_async.py
+            :start-after: [START create_metrics_client_sovereign_cloud_async]
+            :end-before: [END create_metrics_client_sovereign_cloud_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, endpoint: str, credential: "AsyncTokenCredential", **kwargs: Any) -> None:
@@ -135,6 +153,14 @@ async def query_resources(
         :return: A list of MetricsQueryResult objects.
         :rtype: list[~azure.monitor.querymetrics.MetricsQueryResult]
         :raises ~azure.core.exceptions.HttpResponseError:
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_metrics_query_async.py
+                :start-after: [START send_metrics_batch_query_async]
+                :end-before: [END send_metrics_batch_query_async]
+                :language: python
+                :caption: Get a response for a batch metrics query.
         """
         if not resource_ids:
             raise ValueError("'resource_ids' must be provided and must not be empty.")
diff --git a/sdk/monitor/azure-monitor-querymetrics/samples/README.md b/sdk/monitor/azure-monitor-querymetrics/samples/README.md
@@ -0,0 +1,64 @@
+---
+page_type: sample
+languages:
+  - python
+products:
+    - azure
+    - azure-monitor
+urlFragment: querymetrics-azuremonitor-samples
+---
+
+# Azure Monitor Query Metrics client library Python samples
+
+## Samples
+
+The following code samples show common scenarios with the Azure Monitor Query Metrics client library.
+
+For examples on authenticating with the Azure Monitor service, see [sample_authentication.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication.py) and [sample_authentication_async.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication_async.py).
+
+### Metrics query samples
+
+- [Send a query to resources using MetricsClient](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query.py) ([async sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query_async.py))
+
+## Prerequisites
+
+- Python 3.9 or later
+- An [Azure subscription][azure_subscription]
+- Authorization to read metrics data at the Azure subscription level. For example, the [Monitoring Reader role](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/monitor#monitoring-reader) on the subscription containing the resources to be queried.
+- Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).
+
+## Setup
+
+1. Install the latest version of the Azure Monitor Query Metrics library:
+
+  ```bash
+  pip install azure-monitor-querymetrics
+  ```
+
+2. Clone or download this sample repository.
+3. Open the *samples* folder in Visual Studio Code or your IDE of choice.
+4. To run the samples, you need `azure-identity`.
+
+  ```bash
+  pip install azure-identity
+  ```
+
+5. To run the async samples, you need an asynchronous HTTP framework like `aiohttp`:
+
+  ```bash
+  pip install aiohttp
+  ```
+
+## Run the samples
+
+1. Open a terminal window and `cd` to the directory that the samples are saved in.
+2. Set the environment variables specified in the sample file you wish to run.
+3. Follow the usage described in the file. For example, `python sample_metrics_query.py`.
+
+## Next steps
+
+To learn more about Azure Monitor, see the [Azure Monitor service documentation](https://learn.microsoft.com/azure/azure-monitor/).
+
+<!-- LINKS -->
+
+[azure_subscription]: https://azure.microsoft.com/free/python/
diff --git a/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication.py b/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication.py
@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""
+FILE: sample_authentication.py
+DESCRIPTION:
+    This sample demonstrates how to authenticate to the Azure Monitor service using MetricsClient.
+USAGE:
+    python sample_authentication.py
+
+This example uses DefaultAzureCredential, which requests a token from Microsoft Entra ID.
+For more information on DefaultAzureCredential, see https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential.
+"""
+
+
+def create_metrics_client():
+    # [START create_metrics_client]
+    from azure.identity import DefaultAzureCredential
+    from azure.monitor.querymetrics import MetricsClient
+
+    credential = DefaultAzureCredential()
+    client = MetricsClient("https://eastus.metrics.monitor.azure.com", credential)
+    # [END create_metrics_client]
+
+
+def create_metrics_client_sovereign_cloud():
+    # [START create_metrics_client_sovereign_cloud]
+    from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+    from azure.monitor.querymetrics import MetricsClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = MetricsClient(
+        "https://usgovvirginia.metrics.monitor.azure.us",
+        credential,
+        audience="https://metrics.monitor.azure.us",
+    )
+    # [END create_metrics_client_sovereign_cloud]
+
+
+if __name__ == "__main__":
+    create_metrics_client()
+    create_metrics_client_sovereign_cloud()
diff --git a/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication_async.py b/sdk/monitor/azure-monitor-querymetrics/samples/sample_authentication_async.py
@@ -0,0 +1,47 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""
+FILE: sample_authentication_async.py
+DESCRIPTION:
+    This sample demonstrates how to authenticate to the Azure Monitor service using MetricsClient.
+USAGE:
+    python sample_authentication_async.py
+
+This example uses DefaultAzureCredential, which requests a token from Microsoft Entra ID.
+For more information on DefaultAzureCredential, see https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential.
+"""
+import asyncio
+
+
+async def create_metrics_client_async():
+    # [START create_metrics_client_async]
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.querymetrics.aio import MetricsClient
+
+    credential = DefaultAzureCredential()
+    client = MetricsClient("https://eastus.metrics.monitor.azure.com", credential)
+    # [END create_metrics_client_async]
+
+
+async def create_metrics_client_sovereign_cloud_async():
+    # [START create_metrics_client_sovereign_cloud_async]
+    from azure.identity import AzureAuthorityHosts
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.querymetrics.aio import MetricsClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = MetricsClient(
+        "https://usgovvirginia.metrics.monitor.azure.us",
+        credential,
+        audience="https://metrics.monitor.azure.us",
+    )
+    # [END create_metrics_client_sovereign_cloud_async]
+
+
+async def main():
+    await create_metrics_client_async()
+    await create_metrics_client_sovereign_cloud_async()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query.py b/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query.py
@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""
+FILE: sample_metrics_query.py
+DESCRIPTION:
+    This sample demonstrates authenticating the MetricsClient and retrieving the "Ingress"
+    metric along with the "Average" aggregation type for multiple resources.
+    The query will execute over a timespan of 2 hours with a granularity of 5 minutes.
+USAGE:
+    python sample_metrics_query.py
+    1) AZURE_METRICS_ENDPOINT - The regional metrics endpoint to use (i.e. https://westus3.metrics.monitor.azure.com)
+
+    This example uses DefaultAzureCredential, which requests a token from Microsoft Entra ID.
+    For more information on DefaultAzureCredential, see https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#defaultazurecredential.
+
+    In this example, storage account resources are queried for metrics.
+"""
+
+# [START send_metrics_batch_query]
+from datetime import timedelta
+import os
+
+from azure.core.exceptions import HttpResponseError
+from azure.identity import DefaultAzureCredential
+from azure.monitor.querymetrics import MetricsClient, MetricAggregationType
+
+
+endpoint = os.environ["AZURE_METRICS_ENDPOINT"]
+
+credential = DefaultAzureCredential()
+client = MetricsClient(endpoint, credential)
+
+resource_ids = [
+    "/subscriptions/<id>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<account-1>",
+    "/subscriptions/<id>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<account-2>",
+]
+
+try:
+    response = client.query_resources(
+        resource_ids=resource_ids,
+        metric_namespace="Microsoft.Storage/storageAccounts",
+        metric_names=["Ingress"],
+        timespan=timedelta(hours=2),
+        granularity=timedelta(minutes=5),
+        aggregations=[MetricAggregationType.AVERAGE],
+    )
+
+    for metrics_query_result in response:
+        for metric in metrics_query_result.metrics:
+            print(metric.name + " -- " + metric.display_description)
+            for time_series_element in metric.timeseries:
+                for metric_value in time_series_element.data:
+                    print("The ingress at {} is {}".format(metric_value.timestamp, metric_value.average))
+except HttpResponseError as err:
+    print("something fatal happened")
+    print(err)
+# [END send_metrics_batch_query]
diff --git a/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query_async.py b/sdk/monitor/azure-monitor-querymetrics/samples/sample_metrics_query_async.py
diff --git a/sdk/monitor/azure-monitor-querymetrics/setup.py b/sdk/monitor/azure-monitor-querymetrics/setup.py
