在用于 Python 的 Azure 库中配置日志记录

基于 azure.core 页面的用于 Python 的 Azure 库使用标准 Python 日志记录库提供日志记录输出。

使用日志记录的一般过程如下所示:

  1. 获取所需库的日志记录对象,并设置日志记录级别。
  2. 注册日志记录流的处理程序。
  3. 若要包含 HTTP 信息,请将 logging_enable=True 参数传递给客户端对象构造函数、凭据对象构造函数或特定方法。

本文余下部分提供了详细信息。

一般来说,了解库中日志记录使用情况的最佳方法是在 github.com/Azure/azure-sdk-for-python 中浏览 SDK 源代码。 建议你在本地克隆此存储库,以便可以在需要时轻松搜索详细信息,如以下部分所示。

设置日志记录级别

import logging

# ...

# Acquire the logger for a library (azure.mgmt.resource in this example)
logger = logging.getLogger('azure.mgmt.resource')

# Set the desired logging level
logger.setLevel(logging.DEBUG)
  • 此示例获取 azure.mgmt.resource 库的记录器,然后将日志记录级别设置为 logging.DEBUG
  • 你可以随时调用 logger.setLevel 以更改不同代码片段的日志记录级别。

若要设置不同库的级别,请在 logging.getLogger 调用中使用该库的名称。 例如,azure eventhubs 库提供名为 azure.eventhubs 的记录器,azure-storage-queue 库提供名为 azure.storage.queue 的记录器,依此类推。 (SDK 源代码经常使用 logging.getLogger(__name__) 语句,该语句使用包含模块的名称获取记录器。)

你还可以使用更常见的命名空间。 例如,

import logging

# Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.storage')
logger.setLevel(logging.INFO)

# Set the logging level for all azure-* libraries
logger = logging.getLogger('azure')
logger.setLevel(logging.ERROR)

请注意,azure 记录器由某些库使用,而不是由特定的记录器使用。 例如,azure-storage-blob 库使用 azure 记录器。

可使用 logger.isEnabledFor 方法来检查是否已启用任何给定的日志记录级别:

print(f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, " \
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, " \
    f"INFO={logger.isEnabledFor(logging.INFO)}, " \
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}")

日志记录级别与标准日志记录库级别相同。 下表描述了这些用于 Python 的 Azure 库中的日志记录级别的一般用法:

日志记录级别 典型用法
logging.ERROR 应用程序不太可能恢复的故障(如内存不足)。
logging.WARNING(默认) 函数无法执行其预期任务(但不是在函数可以恢复时,如重试 REST API 调用)。 函数通常会在引发异常时记录警告。 警告级别会自动启用错误级别。
logging.INFO 函数正常运行,或者服务调用被取消。 信息事件通常包括请求、响应和标头。 信息级别会自动启用错误和警告级别。
logging.DEBUG 通常用于故障排除的详细信息,其中包括异常的堆栈跟踪。 调试级别会自动启用信息、警告和错误级别。 警告:如果还设置 logging_enable=True,则调试级别将包含敏感信息,例如标头中的帐户密钥和其他凭据。 确保保护这些日志,以避免危及安全性。
logging.NOTSET 禁用所有日志记录。

特定于库的日志记录级别行为

每个级别的确切日志记录行为取决于相关的库。 某些库(如 azure.eventhub)会执行大量日志记录,而其他库执行的记录则非常少。

检查库的确切日志记录的最佳方式是在 Azure SDK for Python 源代码中搜索日志记录级别:

  1. 在存储库文件夹中,导航到“sdk”文件夹,然后导航到所需特定服务的文件夹。

  2. 在该文件夹中,搜索以下任何字符串:

    • _LOGGER.error
    • _LOGGER.warning
    • _LOGGER.info
    • _LOGGER.debug

注册日志流处理程序

若要捕获日志记录输出,必须在代码中注册至少一个日志流处理程序:

import logging

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

此示例注册的处理程序可将日志输出定向到 stdout。 可以使用 Python 文档中 logging.handlers 部分所述的其他类型的处理程序,也可以使用标准的 logging.basicConfig 方法。

为客户端对象或操作启用 HTTP 日志记录

默认情况下,Azure 库中的日志记录不包含任何 HTTP 信息。 若要将 HTTP 信息包括在日志输出中(作为调试级别),必须将 logging_enable=True 专门传递给客户端、凭据对象构造函数或特定方法。

警告:HTTP 日志记录可以显示包含敏感信息(例如,标头中的帐户密钥和其他凭据)。 确保保护这些日志,以避免危及安全性。

为客户端对象启用 HTTP 日志记录(调试级别)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the client object when using DEBUG level
# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential(), logging_enable=True)

为客户端对象启用 HTTP 日志记录可为通过该对象调用的所有操作启用日志记录。

为凭据对象启用 HTTP 日志记录(调试级别)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# Enable HTTP logging on the credential object when using DEBUG level
credential = DefaultAzureCredential(logging_enable=True)

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, credential)

为凭据对象启用 HTTP 日志记录可为通过该对象调用的所有操作(而不是为不涉及身份验证的客户端对象中的操作)启用日志记录。

为单个方法启用日志记录(调试级别)

from azure.storage.blob import BlobClient
from azure.identity import DefaultAzureCredential

# endpoint is the Blob storage URL.
client = BlobClient(endpoint, DefaultAzureCredential())

# Enable HTTP logging for only this operation when using DEBUG level
client.create_container("container01", logging_enable=True)

日志记录输出示例

以下代码显示在示例:使用存储帐户中,并且附带有启用 DEBUG 和 HTTP 日志记录的代码:

import os
import sys
import logging
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobClient

logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Set the logging level for the azure.storage.blob library
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()
storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]

# Enable logging on the client object
blob_client = BlobClient(storage_url, container_name="blob-container-01",
    blob_name="sample-blob9.txt", credential=credential)

with open("./sample-source.txt", "rb") as data:
    blob_client.upload_blob(data, logging_enable=True)

日志记录输出如下所示:

Request URL: 'https://pythonsdkstorage12345.blob.core.windows.net/blob-container-01/sample-blob.txt'
Request method: 'PUT'
Request headers:
    'Content-Type': 'application/octet-stream'
    'Content-Length': '79'
    'x-ms-version': '2019-07-07'
    'x-ms-blob-type': 'BlockBlob'
    'If-None-Match': '*'
    'x-ms-date': 'Mon, 01 Jun 2020 22:54:14 GMT'
    'x-ms-client-request-id': 'd081f88e-a45a-11ea-b9eb-0c5415dfd03a'
    'User-Agent': 'azsdk-python-storage-blob/12.3.1 Python/3.8.3 (Windows-10-10.0.18362-SP0)'
    'Authorization': '*****'
Request body:
b"Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob.\r\n"
Response status: 201
Response headers:
    'Content-Length': '0'
    'Content-MD5': 'kvMIzjEi6O8EqTVnZJNakQ=='
    'Last-Modified': 'Mon, 01 Jun 2020 22:54:14 GMT'
    'ETag': '"0x8D8067EB52FF7BC"'
    'Server': 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0'
    'x-ms-request-id': '5df479b1-f01e-00d0-5b67-382916000000'
    'x-ms-client-request-id': 'd081f88e-a45a-11ea-b9eb-0c5415dfd03a'
    'x-ms-version': '2019-07-07'
    'x-ms-content-crc64': 'QmecNePSHnY='
    'x-ms-request-server-encrypted': 'true'
    'Date': 'Mon, 01 Jun 2020 22:54:14 GMT'
Response content: