From 4e58a380440e4d817638601f96528c2c068a34b2 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Wed, 21 Jul 2021 14:20:29 -0700 Subject: [PATCH 1/6] Update and improve README --- sdk/monitor/azure-monitor-query/README.md | 84 ++++++++++++++++++- .../azure/monitor/query/_models.py | 2 +- 2 files changed, 83 insertions(+), 3 deletions(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index 9c2e0cf18d81..2d088e32cafe 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -20,7 +20,7 @@ Install the Azure Monitor Query client library for Python with [pip][pip]: pip install azure-monitor-query --pre ``` -### Authenticate the client +### Create and Authenticate the client A **token credential** is necessary to instantiate both the LogsQueryClient and the MetricsQueryClient object. ```Python @@ -102,6 +102,11 @@ time-stamped data. Each set of metric values is a time series with the following This sample shows getting a log query. to handle the response and view it in a tabular form, the [pandas](https://pypi.org/project/pandas/) library is used. Please look at the samples if you don't want to use the pandas library. +#### Specifying a duration + +The `duration` parameter can be used to specify the time duration for which to query the data. This can also be accompanied with either `start_time` or `end_time`. If either `start_time` or `end_time` are not provided, the current time is taken as the end time. +Alternatively, the `start_time` and `end_time` keyword arguments can be provided together instead of `duration` parameter like shown in the example below. + ```Python import os import pandas as pd @@ -117,7 +122,6 @@ client = LogsQueryClient(credential) # Response time trend # request duration over the last 12 hours. query = """AppRequests | -where TimeGenerated > ago(12h) | summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId""" # returns LogsQueryResults @@ -136,6 +140,19 @@ for table in response.tables: print(df) ``` +#### Single query on multiple workspaces. + +`additional_workspaces` param can be used to pass a list of workspaces that are included in the query when querying a single query over multiple workspaces. These can be qualified workspace names, workspsce Ids or Azure resource Ids. +Note that a primary `workspace_id` must still be provided when querying additional workspaces like in the snippet below. + +```Python + client.query( + os.environ['LOG_WORKSPACE_ID'], + query, + additional_workspaces=['', ''] + ) +``` + ### Get Logs for multiple queries This sample shows sending multiple queries at the same time using batch query API. For each query, a `LogQueryRequest` object can be used. Alternatively, a dictionary can be used as well. @@ -208,6 +225,8 @@ response = client.query( This example shows getting the metrics for an EventGrid subscription. The resource URI is that of an eventgrid topic. +**Note** The resource URI must be that of the resource for which metrics are being queried. It's normally of the format, `/subscriptions//resourceGroups//providers//topics/`. + ```Python import os from datetime import timedelta @@ -234,6 +253,67 @@ for metric in response.metrics: print(metric_value.time_stamp) ``` +### Handling the response for metrics + +The metrics query API returns a `MetricsResult` object. This object has a list of `Metric` type along with other params like `interval`, `namespace` and `timespan`. + +This cab ne fetched using the `metrics` param. + +Each of the item in this list is a `Metric` object that contains a list of `TimeSeriesElement`. Each of the timeseries elements contain `data` and `metadata_values` params. + + +#### Object heirarchy of the response + +``` +MetricsResult +|---interval +|---timespan +|---cost +|---namespace +|---resourceregion +|---metrics (list of `Metric` objects) + |---id + |---type + |---name + |---unit + |---timeseries (list of `TimeSeriesElement` objects) + |---metadata_values + |---data (list of data points represented by `MetricValue` objects) +``` + +#### Sample usage of the API to handle response. + +```Python +import os +from datetime import datetime, timedelta +from azure.monitor.query import MetricsQueryClient, AggregationType +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = MetricsQueryClient(credential) + +metrics_uri = os.environ['METRICS_RESOURCE_URI'] +response = client.query( + metrics_uri, + metric_names=["MatchedEventCount"], + start_time=datetime(2021, 6, 21), + duration=timedelta(days=1), + aggregations=[AggregationType.COUNT] + ) + +for metric in response.metrics: + print(metric.name) + for time_series_element in metric.timeseries: + for metric_value in time_series_element.data: + if metric_value.count != 0: + print( + "There are {} matched events at {}".format( + metric_value.count, + metric_value.time_stamp + ) + ) +``` + ## Troubleshooting - Enable `azure.monitor.query` logger to collect traces from the library. diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_models.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_models.py index 49491f6b9965..f05b05332df4 100644 --- a/sdk/monitor/azure-monitor-query/azure/monitor/query/_models.py +++ b/sdk/monitor/azure-monitor-query/azure/monitor/query/_models.py @@ -483,7 +483,7 @@ class TimeSeriesElement(object): :keyword metadata_values: the metadata values returned if $filter was specified in the call. :paramtype metadata_values: list[~monitor_query_client.models.MetadataValue] - :keyword data: An array of data points representing the metric values. This is only returned if + :keyword data: An array of data points representing the metric values. This is only returned if a result type of data is specified. :paramtype data: list[~monitor_query_client.models.MetricValue] """ From b85f5517abb68dbe160513b6aa50e57cd9d34836 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Thu, 22 Jul 2021 11:30:48 -0700 Subject: [PATCH 2/6] Update sdk/monitor/azure-monitor-query/README.md --- sdk/monitor/azure-monitor-query/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index 2d088e32cafe..c80eaf70780d 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -147,7 +147,7 @@ Note that a primary `workspace_id` must still be provided when querying addition ```Python client.query( - os.environ['LOG_WORKSPACE_ID'], + , query, additional_workspaces=['', ''] ) From 5d669667e8f9c7016009264b19dd4b15d2107e99 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Fri, 23 Jul 2021 12:15:08 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com> --- sdk/monitor/azure-monitor-query/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index c80eaf70780d..d1ace80c0920 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -255,11 +255,11 @@ for metric in response.metrics: ### Handling the response for metrics -The metrics query API returns a `MetricsResult` object. This object has a list of `Metric` type along with other params like `interval`, `namespace` and `timespan`. +The metrics query API returns a `MetricsResult` object. This `MetricsResult` object has multiple properties, including: a list of `Metric` type objects, `interval`, `namespace`, and `timespan`. This cab ne fetched using the `metrics` param. -Each of the item in this list is a `Metric` object that contains a list of `TimeSeriesElement`. Each of the timeseries elements contain `data` and `metadata_values` params. +Each of the item in this list is a `Metric` object that contains a list of `TimeSeriesElement` objects. Each `TimeSeriesElement` contains `data` and `metadata_values` params. #### Object heirarchy of the response From 63e3ae6cb2443e479c8cb902180d09f71c1c8b71 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Fri, 23 Jul 2021 12:15:20 -0700 Subject: [PATCH 4/6] Update sdk/monitor/azure-monitor-query/README.md Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com> --- sdk/monitor/azure-monitor-query/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index d1ace80c0920..c472fb9fc208 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -257,7 +257,7 @@ for metric in response.metrics: The metrics query API returns a `MetricsResult` object. This `MetricsResult` object has multiple properties, including: a list of `Metric` type objects, `interval`, `namespace`, and `timespan`. -This cab ne fetched using the `metrics` param. +This can be fetched using the `metrics` param. Each of the item in this list is a `Metric` object that contains a list of `TimeSeriesElement` objects. Each `TimeSeriesElement` contains `data` and `metadata_values` params. From 29f70e4961b99839dce8b9705112fac4a939c7c6 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Fri, 23 Jul 2021 13:30:11 -0700 Subject: [PATCH 5/6] Update sdk/monitor/azure-monitor-query/README.md Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com> --- sdk/monitor/azure-monitor-query/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index c472fb9fc208..85e1ad08a86e 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -142,7 +142,7 @@ for table in response.tables: #### Single query on multiple workspaces. -`additional_workspaces` param can be used to pass a list of workspaces that are included in the query when querying a single query over multiple workspaces. These can be qualified workspace names, workspsce Ids or Azure resource Ids. +`additional_workspaces` param can be used to pass a list of workspaces that are included in the query when querying a single query over multiple workspaces. These can be qualified workspace names, workspace IDs or Azure resource IDs. Note that a primary `workspace_id` must still be provided when querying additional workspaces like in the snippet below. ```Python From 43b502bc667ade2c6273c9fb0e4c12f933297c11 Mon Sep 17 00:00:00 2001 From: Rakshith Bhyravabhotla Date: Fri, 23 Jul 2021 13:30:17 -0700 Subject: [PATCH 6/6] Update sdk/monitor/azure-monitor-query/README.md Co-authored-by: swathipil <76007337+swathipil@users.noreply.github.com> --- sdk/monitor/azure-monitor-query/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/monitor/azure-monitor-query/README.md b/sdk/monitor/azure-monitor-query/README.md index 85e1ad08a86e..4fc2e60318ba 100644 --- a/sdk/monitor/azure-monitor-query/README.md +++ b/sdk/monitor/azure-monitor-query/README.md @@ -259,7 +259,7 @@ The metrics query API returns a `MetricsResult` object. This `MetricsResult` obj This can be fetched using the `metrics` param. -Each of the item in this list is a `Metric` object that contains a list of `TimeSeriesElement` objects. Each `TimeSeriesElement` contains `data` and `metadata_values` params. +Each of the items in this list is a `Metric` object that contains a list of `TimeSeriesElement` objects. Each `TimeSeriesElement` contains `data` and `metadata_values` properties. #### Object heirarchy of the response