[Monitor] Improve docs regarding sovereign clouds

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

@@ -69,7 +69,12 @@ logs_client = LogsIngestionClient(endpoint, credential)
 By default, `LogsIngestionClient` is configured to connect to the public Azure cloud. To connect to non-public Azure clouds, some additional configuration is required. The appropriate scope for authentication must be provided using the `credential_scopes` keyword argument. The following example shows how to configure the client to connect to Azure US Government:
 
 ```python
-logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])
+from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+from azure.monitor.ingestion import LogsIngestionClient
+
+# Authority can also be set via the AZURE_AUTHORITY_HOST environment variable.
+credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+logs_client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"])
 ```
 
 ## Key concepts

sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/_patch.py

@@ -21,6 +21,24 @@ class LogsIngestionClient(GeneratedClient):
     :keyword api_version: Api Version. Default value is "2023-01-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_client_public_cloud]
+            :end-before: [END create_client_public_cloud]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsIngestionClient with DefaultAzureCredential.
+
+    .. admonition:: Example:
+
+       .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_client_sovereign_cloud]
+            :end-before: [END create_client_sovereign_cloud]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsIngestionClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
 

sdk/monitor/azure-monitor-ingestion/azure/monitor/ingestion/aio/_patch.py

@@ -21,6 +21,24 @@ class LogsIngestionClient(GeneratedClient):
     :keyword api_version: Api Version. Default value is "2023-01-01". Note that overriding
      this default value may result in unsupported behavior.
     :paramtype api_version: str
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_client_public_cloud_async]
+            :end-before: [END create_client_public_cloud_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsIngestionClient with DefaultAzureCredential.
+
+    .. admonition:: Example:
+
+       .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_client_sovereign_cloud_async]
+            :end-before: [END create_client_sovereign_cloud_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsIngestionClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
 

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

@@ -14,6 +14,7 @@ This library allows you to send data from virtually any source to supported buil
 
 |**File Name**|**Description**|
 |-------------|---------------|
+|[sample_authentication.py][sample_authentication] and [sample_authentication_async.py][sample_authentication_async]|Authenticate a client with the public cloud and a sovereign cloud.|
 |[sample_send_small_logs.py][sample_send_small_logs] and [sample_send_small_logs_async.py][sample_send_small_logs_async]|Send a small number of logs to a Log Analytics workspace.|
 |[sample_custom_error_callback.py][sample_custom_error_callback] and [sample_custom_error_callback_async.py][sample_custom_error_callback_async]|Use error callbacks to customize how errors are handled during upload. |
 |[sample_upload_file_contents.py][sample_upload_file_contents] and [sample_upload_file_contents_async.py][sample_upload_file_contents_async]|Upload the contents of a file to a Log Analytics workspace.|
@@ -72,6 +73,8 @@ To learn more about Azure Monitor, see the [Azure Monitor service documentation]
 
 
 <!-- Sample links -->
+[sample_authentication]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py
+[sample_authentication_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py
 [sample_send_small_logs]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_send_small_logs.py
 [sample_send_small_logs_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_send_small_logs_async.py
 [sample_custom_error_callback]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/monitor/azure-monitor-ingestion/samples/sample_custom_error_callback.py

sdk/monitor/azure-monitor-ingestion/samples/async_samples/sample_authentication_async.py

@@ -0,0 +1,51 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: sample_authentication_async.py
+
+DESCRIPTION:
+    This sample demonstrates how to authenticate the LogsIngestionClient.
+
+    Note: This sample requires the azure-identity library.
+
+USAGE:
+    python sample_authentication_async.py
+"""
+
+import asyncio
+
+
+async def authenticate_public_cloud():
+    # [START create_client_public_cloud_async]
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.ingestion.aio import LogsIngestionClient
+
+    credential = DefaultAzureCredential()
+    endpoint = "https://example.ingest.monitor.azure.com"
+    client = LogsIngestionClient(endpoint, credential)
+    # [END create_client_public_cloud_async]
+
+
+async def authenticate_sovereign_cloud():
+    # [START create_client_sovereign_cloud_async]
+    from azure.identity import AzureAuthorityHosts
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.ingestion.aio import LogsIngestionClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    endpoint = "https://example.ingest.monitor.azure.us"
+    client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"])
+    # [END create_client_sovereign_cloud_async]
+
+
+async def main():
+    await authenticate_public_cloud()
+    await authenticate_sovereign_cloud()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/monitor/azure-monitor-ingestion/samples/sample_authentication.py

@@ -0,0 +1,44 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+"""
+FILE: sample_authentication.py
+
+DESCRIPTION:
+    This sample demonstrates how to authenticate the LogsIngestionClient.
+
+    Note: This sample requires the azure-identity library.
+
+USAGE:
+    python sample_authentication.py
+"""
+
+
+def authenticate_public_cloud():
+    # [START create_client_public_cloud]
+    from azure.identity import DefaultAzureCredential
+    from azure.monitor.ingestion import LogsIngestionClient
+
+    credential = DefaultAzureCredential()
+    endpoint = "https://example.ingest.monitor.azure.com"
+    client = LogsIngestionClient(endpoint, credential)
+    # [END create_client_public_cloud]
+
+
+def authenticate_sovereign_cloud():
+    # [START create_client_sovereign_cloud]
+    from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+    from azure.monitor.ingestion import LogsIngestionClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    endpoint = "https://example.ingest.monitor.azure.us"
+    client = LogsIngestionClient(endpoint, credential, credential_scopes=["https://monitor.azure.us/.default"])
+    # [END create_client_sovereign_cloud]
+
+
+if __name__ == "__main__":
+    authenticate_public_cloud()
+    authenticate_sovereign_cloud()

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

@@ -73,8 +73,15 @@ async_metrics_client = MetricsClient("https://<regional endpoint>", credential)
 By default, `LogsQueryClient` and `MetricsQueryClient` are configured to connect to the public Azure cloud. These can be configured to connect to non-public Azure clouds by passing in the correct `endpoint` argument: For example:
 
 ```python
-logs_query_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.azure.cn/v1")
-metrics_query_client = MetricsQueryClient(credential, endpoint="https://management.chinacloudapi.cn")
+from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+from azure.monitor.query import LogsQueryClient, MetricsQueryClient
+
+# Authority can also be set via the AZURE_AUTHORITY_HOST environment variable.
+credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+
+logs_query_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1")
+metrics_query_client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net")
+
 ```
 
 **Note**: Currently, `MetricsQueryClient` uses the Azure Resource Manager (ARM) endpoint for querying metrics, so you will need the corresponding management endpoint for your cloud when using this client. This is subject to change in the future.

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

@@ -48,6 +48,15 @@ class LogsQueryClient(object):  # pylint: disable=client-accepts-api-version-key
             :language: python
             :dedent: 4
             :caption: Creating the LogsQueryClient with a TokenCredential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_logs_query_client_sovereign_cloud]
+            :end-before: [END create_logs_query_client_sovereign_cloud]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsQueryClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, credential: TokenCredential, **kwargs: Any) -> None:

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

@@ -38,6 +38,15 @@ class MetricsQueryClient(object):  # pylint: disable=client-accepts-api-version-
             :language: python
             :dedent: 4
             :caption: Creating the MetricsQueryClient with a TokenCredential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/sample_authentication.py
+            :start-after: [START create_metrics_query_client_sovereign_cloud]
+            :end-before: [END create_metrics_query_client_sovereign_cloud]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsQueryClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, credential: TokenCredential, **kwargs: Any) -> None:

sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_logs_query_client_async.py

@@ -43,6 +43,15 @@ class LogsQueryClient(object):  # pylint: disable=client-accepts-api-version-key
             :language: python
             :dedent: 4
             :caption: Creating the asynchronous LogsQueryClient with a TokenCredential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_logs_query_client_sovereign_cloud_async]
+            :end-before: [END create_logs_query_client_sovereign_cloud_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the LogsQueryClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None:

sdk/monitor/azure-monitor-query/azure/monitor/query/aio/_metrics_query_client_async.py

@@ -37,6 +37,15 @@ class MetricsQueryClient(object):  # pylint: disable=client-accepts-api-version-
             :language: python
             :dedent: 4
             :caption: Creating the asynchronous MetricsQueryClient with a TokenCredential.
+
+    .. admonition:: Example:
+
+        .. literalinclude:: ../samples/async_samples/sample_authentication_async.py
+            :start-after: [START create_metrics_query_client_sovereign_cloud_async]
+            :end-before: [END create_metrics_query_client_sovereign_cloud_async]
+            :language: python
+            :dedent: 4
+            :caption: Creating the MetricsQueryClient for use with a sovereign cloud (i.e. non-public cloud).
     """
 
     def __init__(self, credential: AsyncTokenCredential, **kwargs: Any) -> None:

sdk/monitor/azure-monitor-query/samples/async_samples/sample_authentication_async.py

@@ -24,6 +24,17 @@ async def create_logs_query_client_async():
     # [END create_logs_query_client_async]
 
 
+async def create_logs_query_client_sovereign_cloud_async():
+    # [START create_logs_query_client_sovereign_cloud_async]
+    from azure.identity import AzureAuthorityHosts
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.query.aio import LogsQueryClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1")
+    # [END create_logs_query_client_sovereign_cloud_async]
+
+
 async def create_metrics_query_client_async():
     # [START create_metrics_query_client_async]
     from azure.identity.aio import DefaultAzureCredential
@@ -34,9 +45,22 @@ async def create_metrics_query_client_async():
     # [END create_metrics_query_client_async]
 
 
+async def create_metrics_query_client_sovereign_cloud_async():
+    # [START create_metrics_query_client_sovereign_cloud_async]
+    from azure.identity import AzureAuthorityHosts
+    from azure.identity.aio import DefaultAzureCredential
+    from azure.monitor.query.aio import MetricsQueryClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net")
+    # [END create_metrics_query_client_sovereign_cloud_async]
+
+
 async def main():
     await create_logs_query_client_async()
+    await create_logs_query_client_sovereign_cloud_async()
     await create_metrics_query_client_async()
+    await create_metrics_query_client_sovereign_cloud_async()
 
 
 if __name__ == '__main__':

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

@@ -23,6 +23,16 @@ def create_logs_query_client():
     # [END create_logs_query_client]
 
 
+def create_logs_query_client_sovereign_cloud():
+    # [START create_logs_query_client_sovereign_cloud]
+    from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+    from azure.monitor.query import LogsQueryClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = LogsQueryClient(credential, endpoint="https://api.loganalytics.us/v1")
+    # [END create_logs_query_client_sovereign_cloud]
+
+
 def create_metrics_query_client():
     # [START create_metrics_query_client]
     from azure.identity import DefaultAzureCredential
@@ -33,6 +43,18 @@ def create_metrics_query_client():
     # [END create_metrics_query_client]
 
 
+def create_metrics_query_client_sovereign_cloud():
+    # [START create_metrics_query_client_sovereign_cloud]
+    from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
+    from azure.monitor.query import MetricsQueryClient
+
+    credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
+    client = MetricsQueryClient(credential, endpoint="https://management.usgovcloudapi.net")
+    # [END create_metrics_query_client_sovereign_cloud]
+
+
 if __name__ == '__main__':
     create_logs_query_client()
+    create_logs_query_client_sovereign_cloud()
     create_metrics_query_client()
+    create_metrics_query_client_sovereign_cloud()