readme + changelog (Azure#19173)

* readme + changelog

* Prepare for release

* codeowners

* Update sdk/monitor/azure-monitor-query/README.md

Author: Rakshith Bhyravabhotla

.github/CODEOWNERS

@@ -49,6 +49,9 @@
 # PRLabel: %Monitor - Exporter
 /sdk/monitor/azure-monitor-opentelemetry-exporter                    @rakshith91 @lmazuel @lzchen
 
+# PRLabel: %Monitor - Log
+/sdk/monitor/azure-monitor-query                                     @rakshith91
+
 # PRLabel: %Consumption
 /sdk/consumption/                                                    @sandeepnl
 

eng/.docsettings.yml

@@ -70,6 +70,7 @@ known_content_issues:
   - ['sdk/core/azure-servicemanagement-legacy/README.md', '#4554']
   - ['sdk/eventgrid/azure-eventgrid/README.md', '#4554']
   - ['sdk/monitor/azure-monitor-query/README.md', '#4554']
+  - ['sdk/monitor/azure-monitor-query/samples/README.md', '#4554']
   - ['sdk/graphrbac/azure-graphrbac/README.md', '#4554']
   - ['sdk/loganalytics/azure-loganalytics/README.md', '#4554']
   - ['sdk/servicebus/azure-servicebus/README.md', '#4554']

sdk/monitor/azure-monitor-query/CHANGELOG.md

@@ -1,9 +1,9 @@
 # Release History
 
-## 1.0.0b1 (Unreleased)
+## 1.0.0b1 (2021-06-10)
 
   **Features**
   - Version (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Monitor Query.
   For more information about this, and preview releases of other Azure SDK libraries, please visit https://azure.github.io/azure-sdk/releases/latest/python.html.
-  - Added `LogsQueryClient` to query log analytics.
-  - Implements the `MetricsQueryClient` for querying metrics, listing namespaces and metric definitions.
+  - Added `~azure.monitor.query.LogsQueryClient` to query log analytics along with `~azure.monitor.query.aio.LogsQueryClient`.
+  - Implements the `~azure.monitor.query.MetricsQueryClient` for querying metrics, listing namespaces and metric definitions along with `~azure.monitor.query.aio.MetricsQueryClient`.

sdk/monitor/azure-monitor-query/README.md

@@ -108,6 +108,8 @@ time-stamped data. Each set of metric values is a time series with the following
 
 ### Get logs for a query
 
+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.
+
 ```Python
 import os
 import pandas as pd
@@ -130,7 +132,12 @@ where TimeGenerated > ago(12h) |
 summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId"""
 
 # returns LogsQueryResults 
-response = client.query(os.environ['LOG_WORKSPACE_ID'], query)
+response = client.query(
+    os.environ['LOG_WORKSPACE_ID'],
+    query,
+    start_time=datetime(2021, 6, 2),
+    end_time=datetime.now()
+    )
 
 if not response.tables:
     print("No results for the query")
@@ -142,6 +149,8 @@ for table in response.tables:
 
 ### 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.
+
 ```Python
 import os
 import pandas as pd
@@ -160,13 +169,14 @@ client = LogsQueryClient(credential)
 requests = [
     LogsQueryRequest(
         query="AzureActivity | summarize count()",
-        timespan="PT1H",
+        duration="PT1H",
         workspace= os.environ['LOG_WORKSPACE_ID']
     ),
     LogsQueryRequest(
         query= """AppRequests | take 10  |
             summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId""",
-        timespan="PT1H",
+        duration="PT1H",
+        start_time=datetime(2021, 6, 2),
         workspace= os.environ['LOG_WORKSPACE_ID']
     ),
     LogsQueryRequest(
@@ -188,6 +198,8 @@ for response in response.responses:
 
 ### Get logs with server timeout
 
+This sample shows setting a server timeout in seconds. A GateWay timeout is raised if the query takes more time than the mentioned timeout. The default is 180 seconds and can be set uptio 10 minutes (600 seconds).
+
 ```Python
 import os
 import pandas as pd
@@ -205,17 +217,15 @@ client = LogsQueryClient(credential)
 
 response = client.query(
     os.environ['LOG_WORKSPACE_ID'],
-    "Perf | summarize count() by bin(TimeGenerated, 4h) | render barchart title='24H Perf events'",
-    server_timeout=10,
+    "range x from 1 to 10000000000 step 1 | count",
+    server_timeout=1,
     )
-
-for table in response.tables:
-    df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])
-    print(df)
 ```
 
 ### Get Metrics
 
+This example shows getting the metrics for an EventGrid subscription. The resource URI is that of an eventgrid topic.
+
 ```Python
 import os
 from azure.monitor.query import MetricsQueryClient
@@ -229,7 +239,20 @@ credential  = ClientSecretCredential(
     )
 
 client = MetricsQueryClient(credential)
-response = client.query(os.environ['METRICS_RESOURCE_URI'], metric_names=["Microsoft.CognitiveServices/accounts"])
+
+metrics_uri = os.environ['METRICS_RESOURCE_URI']
+response = client.query(
+    metrics_uri,
+    metric_names=["PublishSuccessCount"],
+    start_time=datetime(2021, 5, 25),
+    duration='P1D'
+    )
+
+for metric in response.metrics:
+    print(metric.name)
+    for time_series_element in metric.timeseries:
+        for metric_value in time_series_element.data:
+            print(metric_value.time_stamp)
 ```
 
 ## Troubleshooting
@@ -268,9 +291,9 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 
 [azure_cli_link]: https://pypi.org/project/azure-cli/
 [python-query-src]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/
-[python-query-pypi]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/
-[python-query-product-docs]: https://docs.microsoft.com/rest/api/monitor/metrics
-[python-query-ref-docs]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/
+[python-query-pypi]: https://aka.ms/azsdk-python-monitor-query-pypi
+[python-query-product-docs]: https://docs.microsoft.com/azure/azure-monitor/
+[python-query-ref-docs]: https://docs.microsoft.com/python/api/overview/azure/?view=azure-python
 [python-query-samples]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/azure-monitor-query/samples
 [python-query-changelog]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/azure-monitor-query/CHANGELOG.md
 [pip]: https://pypi.org/project/pip/

sdk/monitor/azure-monitor-query/azure/monitor/query/_log_query_client.py

@@ -25,6 +25,15 @@ class LogsQueryClient(object):
     :type credential: ~azure.core.credentials.TokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://api.loganalytics.io'.
     :paramtype endpoint: str
+
+    .. admonition:: Example:
+
+    .. literalinclude:: ../samples/sample_log_query_client.py
+        :start-after: [START client_auth_with_token_cred]
+        :end-before: [END client_auth_with_token_cred]
+        :language: python
+        :dedent: 0
+        :caption: Creating the LogsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential, **kwargs):
@@ -78,6 +87,15 @@ def query(self, workspace_id, query, duration=None, **kwargs):
         :return: QueryResults, or the result of cls(response)
         :rtype: ~azure.monitor.query.LogsQueryResults
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_log_query_client.py
+            :start-after: [START send_logs_query]
+            :end-before: [END send_logs_query]
+            :language: python
+            :dedent: 0
+            :caption: Get a response for a single Log Query
         """
         start = kwargs.pop('start_time', None)
         end = kwargs.pop('end_time', None)
@@ -126,6 +144,15 @@ def batch_query(self, queries, **kwargs):
         :return: BatchResponse, or the result of cls(response)
         :rtype: ~azure.monitor.query.LogsBatchResults
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_batch_query.py
+            :start-after: [START send_batch_query]
+            :end-before: [END send_batch_query]
+            :language: python
+            :dedent: 0
+            :caption: Get a response for multiple Log Queries.
         """
         try:
             queries = [LogsQueryRequest(**q) for q in queries]

sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py

@@ -28,6 +28,15 @@ class MetricsQueryClient(object):
     :type credential: ~azure.core.credentials.TokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://management.azure.com'.
     :paramtype endpoint: str
+
+    .. admonition:: Example:
+
+    .. literalinclude:: ../samples/sample_metrics_query_client.py
+        :start-after: [START metrics_client_auth_with_token_cred]
+        :end-before: [END metrics_client_auth_with_token_cred]
+        :language: python
+        :dedent: 0
+        :caption: Creating the MetricsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential, **kwargs):
@@ -91,6 +100,15 @@ def query(self, resource_uri, metric_names, duration=None, **kwargs):
         :return: Response, or the result of cls(response)
         :rtype: ~azure.monitor.query.MetricsResult
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_metrics_query_client.py
+            :start-after: [START send_metrics_query]
+            :end-before: [END send_metrics_query]
+            :language: python
+            :dedent: 0
+            :caption: Get a response for a single Metrics Query
         """
         start = kwargs.pop('start_time', None)
         end = kwargs.pop('end_time', None)

sdk/monitor/azure-monitor-query/samples/README.md

@@ -0,0 +1,39 @@
+---
+page_type: sample
+languages:
+  - python
+products:
+    - azure
+    - azure-monitor
+urlFragment: query-azuremonitor-samples
+---
+
+# Azure Monitor Query Client Library Python Samples
+
+## Sync samples
+These code samples show common champion scenario operations with the Azure Monitor Query client library.
+
+* Send a single query with LogsQueryClient: [sample_log_query_client.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_log_query_client.py)
+
+* Send multiple queries with LogsQueryClient: [sample_batch_query.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_batch_query.py)
+
+* Send multiple queries with LogsQueryClient as a dictionary: [sample_batch_query_serialized.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_batch_query_serialized.py)
+
+* Send a single query with LogsQueryClient using server timeout: [sample_server_timeout.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_server_timeout.py)
+
+* Send a query using MetricsQueryClient: [sample_metrics_query_client.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_metrics_query_client.py) 
+
+* Get a list of metric namespaces: [sample_metric_namespaces.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_metric_namespaces.py)
+
+* Get a list of metric definitions: [sample_metric_definitions.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/sample_metric_definitions.py)
+
+## Async samples
+These code samples show common champion scenario operations with the Azure Monitor Query client library using the async client.
+
+* Send a single query with LogsQueryClient: [sample_log_query_client_async.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/async_samples/sample_log_query_client_async.py)
+
+* Send a query using MetricsQueryClient: [sample_metrics_query_client_async.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/async_samples/sample_metrics_query_client_async.py) 
+
+* Get a list of metric namespaces: [sample_metric_namespaces_async.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/async_samples/sample_metric_namespaces_async.py)
+
+* Get a list of metric definitions: [sample_metric_definitions_async.py](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-query/samples/async_samples/sample_metric_definitions_async.py)

sdk/monitor/azure-monitor-query/samples/sample_batch_query.py

@@ -16,6 +16,7 @@
 
 client = LogsQueryClient(credential)
 
+# [START send_batch_query]
 requests = [
     LogsQueryRequest(
         query="AzureActivity | summarize count()",
@@ -44,4 +45,6 @@
     else:
         for table in body.tables:
             df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])
-            print(df)
+            print(df)
+
+# [END send_batch_query]

sdk/monitor/azure-monitor-query/samples/sample_log_query_client.py

@@ -7,17 +7,19 @@
 from azure.monitor.query import LogsQueryClient
 from azure.identity import ClientSecretCredential
 
-
+# [START client_auth_with_token_cred]
 credential  = ClientSecretCredential(
         client_id = os.environ['AZURE_CLIENT_ID'],
         client_secret = os.environ['AZURE_CLIENT_SECRET'],
         tenant_id = os.environ['AZURE_TENANT_ID']
     )
 
 client = LogsQueryClient(credential)
+# [END client_auth_with_token_cred]
 
 # Response time trend 
 # request duration over the last 12 hours. 
+# [START send_logs_query]
 query = """AppRequests | 
 where TimeGenerated > ago(12h) | 
 summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId"""
@@ -31,7 +33,7 @@
 for table in response.tables:
     df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])
     print(df)
-
+# [END send_logs_query]
 """
     TimeGenerated                                        _ResourceId          avgRequestDuration
 0   2021-05-27T08:40:00Z  /subscriptions/faa080af-c1d8-40ad-9cce-e1a450c...  27.307699999999997

sdk/monitor/azure-monitor-query/samples/sample_metrics_query_client.py

@@ -9,14 +9,17 @@
 
 urllib3.disable_warnings()
 
+# [START metrics_client_auth_with_token_cred]
 credential  = ClientSecretCredential(
         client_id = os.environ['AZURE_CLIENT_ID'],
         client_secret = os.environ['AZURE_CLIENT_SECRET'],
         tenant_id = os.environ['AZURE_TENANT_ID']
     )
 
 client = MetricsQueryClient(credential)
+# [END metrics_client_auth_with_token_cred]
 
+# [START send_metrics_query]
 metrics_uri = os.environ['METRICS_RESOURCE_URI']
 response = client.query(
     metrics_uri,
@@ -30,4 +33,4 @@
     for time_series_element in metric.timeseries:
         for metric_value in time_series_element.data:
             print(metric_value.time_stamp)
- 
+# [END send_metrics_query]