[Monitor Query] Update docstrings/samples (Azure#30811)

This cleans up the samples and adds a new sample for async batch queries. New authentication samples were added to cleanly organize code snippets for class docstrings. Signed-off-by: Paul Van Eck <[email protected]>
azure-sdk · Jun 27, 2023 · 4bbd687 · 4bbd687
1 parent e016b9b
commit 4bbd687
Show file tree

Hide file tree

Showing 26 changed files with 553 additions and 286 deletions.
diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_logs_query_client.py
@@ -31,21 +31,21 @@ class LogsQueryClient(object):  # pylint: disable=client-accepts-api-version-key
     apps can be consolidated into a single Azure Log Analytics workspace.
 
     The various data types can be analyzed together using the
-    [Kusto Query Language](https://docs.microsoft.com/azure/data-explorer/kusto/query/)
-
-    .. admonition:: Example:
-
-    .. literalinclude:: ../samples/sample_single_logs_query.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.
+    [Kusto Query Language](https://learn.microsoft.com/azure/data-explorer/kusto/query/)
 
     :param credential: The credential to authenticate the client.
     :type credential: ~azure.core.credentials.TokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://api.loganalytics.io/v1'.
     :paramtype endpoint: Optional[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_logs_query_client]
+            :end-before: [END create_logs_query_client]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential: TokenCredential, **kwargs: Any) -> None:
@@ -81,7 +81,7 @@ def query_workspace(
          Azure portal.
         :type workspace_id: str
         :param query: The Kusto query. Learn more about the `Kusto query syntax
-         <https://docs.microsoft.com/azure/data-explorer/kusto/query/>`_.
+         <https://learn.microsoft.com/azure/data-explorer/kusto/query/>`_.
         :type query: str
         :keyword timespan: Required. The timespan for which to query the data. This can be a timedelta,
          a timedelta and a start datetime, or a start datetime/end datetime. Set to None to not constrain
@@ -103,12 +103,12 @@ def query_workspace(
 
         .. admonition:: Example:
 
-        .. literalinclude:: ../samples/sample_single_logs_query.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
+            .. literalinclude:: ../samples/sample_logs_single_query.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.
         """
         timespan_iso = construct_iso8601(timespan)
         include_statistics = kwargs.pop("include_statistics", False)
@@ -157,12 +157,12 @@ def query_batch(
 
         .. admonition:: Example:
 
-        .. literalinclude:: ../samples/sample_batch_query.py
-            :start-after: [START send_query_batch]
-            :end-before: [END send_query_batch]
-            :language: python
-            :dedent: 0
-            :caption: Get a response for multiple Log Queries.
+            .. literalinclude:: ../samples/sample_batch_query.py
+                :start-after: [START send_query_batch]
+                :end-before: [END send_query_batch]
+                :language: python
+                :dedent: 0
+                :caption: Execute multiple queries in a batch.
         """
         try:
             queries = [LogsBatchQuery(**cast(Dict, q)) for q in queries]
@@ -199,7 +199,7 @@ def query_resource(
          '/subscriptions/<sid>/resourceGroups/<rg>/providers/<providerName>/<resourceType>/<resourceName>'.
         :type resource_id: str
         :param query: The Kusto query. Learn more about the `Kusto query syntax
-         <https://docs.microsoft.com/azure/data-explorer/kusto/query/>`_.
+         <https://learn.microsoft.com/azure/data-explorer/kusto/query/>`_.
         :type query: str
         :keyword timespan: Required. The timespan for which to query the data. This can be a timedelta,
          a timedelta and a start datetime, or a start datetime/end datetime. Set to None to not constrain
@@ -221,12 +221,12 @@ def query_resource(
 
         .. admonition:: Example:
 
-        .. literalinclude:: ../samples/sample_resource_logs_query.py
-            :start-after: [START resource_logs_query]
-            :end-before: [END resource_logs_query]
-            :language: python
-            :dedent: 0
-            :caption: Get a response for a single query on a resource's logs.
+            .. literalinclude:: ../samples/sample_resource_logs_query.py
+                :start-after: [START resource_logs_query]
+                :end-before: [END resource_logs_query]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single query on a resource's logs.
         """
         timespan_iso = construct_iso8601(timespan)
         include_statistics = kwargs.pop("include_statistics", False)

diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/_metrics_query_client.py
@@ -24,19 +24,19 @@ class MetricsQueryClient(object):  # pylint: disable=client-accepts-api-version-
     supporting near real-time scenarios, making them particularly useful for alerting and
     fast detection of issues.
 
-    .. admonition:: Example:
-
-    .. literalinclude:: ../samples/sample_metrics_query.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.
-
     :param credential: The credential to authenticate the client.
     :type credential: ~azure.core.credentials.TokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://management.azure.com'.
     :paramtype endpoint: Optional[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_metrics_query_client]
+            :end-before: [END create_metrics_query_client]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential: TokenCredential, **kwargs: Any) -> None:
@@ -102,12 +102,12 @@ def query_resource(self, resource_uri: str, metric_names: List[str], **kwargs: A
 
         .. 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
+            .. literalinclude:: ../samples/sample_metrics_query.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.
         """
 
         aggregations = kwargs.pop("aggregations", None)
@@ -137,6 +137,15 @@ def list_metric_namespaces(self, resource_uri: str, **kwargs: Any) -> ItemPaged[
         :return: An iterator like instance of either MetricNamespace or the result of cls(response)
         :rtype: ~azure.core.paging.ItemPaged[~azure.monitor.query.MetricNamespace]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_metric_namespaces.py
+                :start-after: [START send_metric_namespaces_query]
+                :end-before: [END send_metric_namespaces_query]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single metric namespaces query.
         """
         start_time = kwargs.pop("start_time", None)
         if start_time:
@@ -163,6 +172,15 @@ def list_metric_definitions(self, resource_uri: str, **kwargs: Any) -> ItemPaged
         :return: An iterator like instance of either MetricDefinition or the result of cls(response)
         :rtype: ~azure.core.paging.ItemPaged[~azure.monitor.query.MetricDefinition]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_metric_definitions.py
+                :start-after: [START send_metric_definitions_query]
+                :end-before: [END send_metric_definitions_query]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single metric definitions query.
         """
         metric_namespace = kwargs.pop("namespace", None)
         res = self._definitions_op.list(

diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py
@@ -26,12 +26,21 @@ class LogsQueryClient(object):  # pylint: disable=client-accepts-api-version-key
     apps can be consolidated into a single Azure Log Analytics workspace.
 
     The various data types can be analyzed together using the
-    [Kusto Query Language](https://docs.microsoft.com/azure/data-explorer/kusto/query/)
+    [Kusto Query Language](https://learn.microsoft.com/azure/data-explorer/kusto/query/)
 
     :param credential: The credential to authenticate the client
     :type credential: ~azure.core.credentials_async.AsyncTokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://api.loganalytics.io/v1'.
     :paramtype endpoint: Optional[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_logs_query_client_async]
+            :end-before: [END create_logs_query_client_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the asynchronous LogsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None:
@@ -68,7 +77,7 @@ async def query_workspace(
          Azure portal.
         :type workspace_id: str
         :param query: The Kusto query. Learn more about the `Kusto query syntax
-         <https://docs.microsoft.com/azure/data-explorer/kusto/query/>`_.
+         <https://learn.microsoft.com/azure/data-explorer/kusto/query/>`_.
         :type query: str
         :keyword timespan: Required. The timespan for which to query the data. This can be a timedelta,
          a timedelta and a start datetime, or a start datetime/end datetime. Set to None to not constrain
@@ -87,6 +96,15 @@ async def query_workspace(
         :return: LogsQueryResult if there is a success or LogsQueryPartialResult when there is a partial success.
         :rtype: ~azure.monitor.query.LogsQueryResult or ~azure.monitor.query.LogsQueryPartialResult
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/async_samples/sample_log_query_async.py
+                :start-after: [START send_logs_query_async]
+                :end-before: [END send_logs_query_async]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single log query.
         """
         timespan_iso = construct_iso8601(timespan)
         include_statistics = kwargs.pop("include_statistics", False)
@@ -131,6 +149,15 @@ async def query_batch(
         :rtype: list[~azure.monitor.query.LogsQueryResult or ~azure.monitor.query.LogsQueryPartialResult
          or ~azure.monitor.query.LogsQueryError]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/async_samples/sample_batch_query_async.py
+                :start-after: [START send_query_batch_async]
+                :end-before: [END send_query_batch_async]
+                :language: python
+                :dedent: 0
+                :caption: Execute multiple queries in a batch.
         """
         try:
             queries = [LogsBatchQuery(**cast(Dict, q)) for q in queries]
@@ -167,7 +194,7 @@ async def query_resource(
          '/subscriptions/<sid>/resourceGroups/<rg>/providers/<providerName>/<resourceType>/<resourceName>'.
         :type resource_id: str
         :param query: The Kusto query. Learn more about the `Kusto query syntax
-         <https://docs.microsoft.com/azure/data-explorer/kusto/query/>`_.
+         <https://learn.microsoft.com/azure/data-explorer/kusto/query/>`_.
         :type query: str
         :keyword timespan: Required. The timespan for which to query the data. This can be a timedelta,
          a timedelta and a start datetime, or a start datetime/end datetime. Set to None to not constrain
@@ -189,12 +216,12 @@ async def query_resource(
 
         .. admonition:: Example:
 
-        .. literalinclude:: ../samples/async_samples/sample_resource_logs_query_async.py
-            :start-after: [START resource_logs_query_async]
-            :end-before: [END resource_logs_query_async]
-            :language: python
-            :dedent: 0
-            :caption: Get a response for a single query on a resource's logs.
+            .. literalinclude:: ../samples/async_samples/sample_resource_logs_query_async.py
+                :start-after: [START resource_logs_query_async]
+                :end-before: [END resource_logs_query_async]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single query on a resource's logs.
         """
         timespan_iso = construct_iso8601(timespan)
         include_statistics = kwargs.pop("include_statistics", False)

diff --git a/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py b/sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py
@@ -27,6 +27,15 @@ class MetricsQueryClient(object):  # pylint: disable=client-accepts-api-version-
     :type credential: ~azure.core.credentials_async.AsyncTokenCredential
     :keyword endpoint: The endpoint to connect to. Defaults to 'https://management.azure.com'.
     :paramtype endpoint: Optional[str]
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_metrics_query_client_async]
+            :end-before: [END create_metrics_query_client_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the asynchronous MetricsQueryClient with a TokenCredential.
     """
 
     def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None:
@@ -92,6 +101,15 @@ async def query_resource(self, resource_uri: str, metric_names: List[str], **kwa
         :return: A MetricsQueryResult object.
         :rtype: ~azure.monitor.query.MetricsQueryResult
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/async_samples/sample_metrics_query_async.py
+                :start-after: [START send_metrics_query_async]
+                :end-before: [END send_metrics_query_async]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single metrics query.
         """
         timespan = construct_iso8601(kwargs.pop("timespan", None))
         # Metric names with commas need to be encoded.
@@ -120,6 +138,15 @@ def list_metric_namespaces(self, resource_uri: str, **kwargs: Any) -> AsyncItemP
         :return: An iterator like instance of either MetricNamespace or the result of cls(response)
         :rtype: ~azure.core.paging.AsyncItemPaged[:class: `~azure.monitor.query.MetricNamespace`]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/async_samples/sample_metric_namespaces_async.py
+                :start-after: [START send_metric_namespaces_query_async]
+                :end-before: [END send_metric_namespaces_query_async]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single metric namespaces query.
         """
         start_time = kwargs.pop("start_time", None)
         if start_time:
@@ -146,6 +173,15 @@ def list_metric_definitions(self, resource_uri: str, **kwargs: Any) -> AsyncItem
         :return: An iterator like instance of either MetricDefinition or the result of cls(response)
         :rtype: ~azure.core.paging.AsyncItemPaged[:class: `~azure.monitor.query.MetricDefinition`]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/async_samples/sample_metric_definitions_async.py
+                :start-after: [START send_metric_definitions_query_async]
+                :end-before: [END send_metric_definitions_query_async]
+                :language: python
+                :dedent: 0
+                :caption: Get a response for a single metric definitions query.
         """
         metric_namespace = kwargs.pop("namespace", None)
         res = self._definitions_op.list(