在適用於 Python 的 Azure 連結庫中設定記錄

發行項
10/03/2024

以 azure.core 為基礎的適用於 Python 的 Azure 連結庫會使用標準 Python 記錄連結庫來提供記錄輸出。

使用記錄的一般程式如下所示：

取得所需連結庫的記錄物件，並設定記錄層級。
註冊記錄數據流的處理程式。
若要包含 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-storage-queue 連結庫提供名為 azure.eventhubsazure.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 連結庫中這些記錄層級的一般用法：

記錄層級	一般用法
伐木。錯誤	應用程式不太可能復原的失敗（例如記憶體不足）。
伐木。WARNING （預設值）	函式無法執行其預定工作（但當函式可以復原時，例如重試 REST API 呼叫）。函式通常會在引發例外狀況時記錄警告。警告層級會自動啟用錯誤層級。
logging.INFO	函式正常運作，或取消服務呼叫。資訊事件通常包括要求、回應和標頭。資訊層級會自動啟用錯誤和警告層級。
伐木。調試	通常用於疑難解答的詳細資訊，並包含例外狀況的堆疊追蹤。偵錯層級會自動啟用資訊、警告和錯誤層級。注意：如果您也設定 `logging_enable=True`，偵錯層級會包含敏感性資訊，例如標頭中的帳戶密鑰和其他認證。請務必保護這些記錄，以避免危害安全性。
伐木。NOTSET	停用所有記錄。

連結庫特定的記錄層級行為

每個層級的確切記錄行為取決於有問題的連結庫。某些連結庫，例如 azure.eventhub，會執行廣泛的記錄，而其他連結庫則很少執行。

檢查連結庫確切記錄的最佳方式是在 Azure SDK for Python 原始程式碼中搜尋記錄層級：

在存放庫資料夾中，流覽至 sdk 資料夾，然後流覽至特定服務感興趣的資料夾。
在該資料夾中，搜尋下列任何字串：
- _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 資訊（作為 DEBUG 層級），您必須明確傳遞 logging_enable=True 至用戶端或認證物件建構函式或特定方法。

警告

HTTP 記錄可以包含敏感性資訊，例如標頭中的帳戶密鑰和其他認證。請務必保護這些記錄，以避免危害安全性。

開啟客戶端物件的 HTTP 記錄（DEBUG 層級）

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 記錄（DEBUG 層級）

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 記錄可針對透過該物件叫用的所有作業進行記錄，但不適用於未涉及驗證的客戶端物件中的作業。

開啟個別方法的記錄功能（DEBUG 層級）

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 logging
import os
import sys
import uuid

from azure.core import exceptions
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)

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)}"
)

try:
    credential = DefaultAzureCredential()
    storage_url = os.environ["AZURE_STORAGE_BLOB_URL"]
    unique_str = str(uuid.uuid4())[0:5]

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

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

except (
    exceptions.ClientAuthenticationError,
    exceptions.HttpResponseError
) as e:
    print(e.message)

輸出如下所示：

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
Request URL: 'https://pythonazurestorage12345.blob.core.windows.net/blob-container-01/sample-blob-5588e.txt'
Request method: 'PUT'
Request headers:
    'Content-Length': '77'
    'x-ms-blob-type': 'BlockBlob'
    'If-None-Match': '*'
    'x-ms-version': '2023-11-03'
    'Content-Type': 'application/octet-stream'
    'Accept': 'application/xml'
    'User-Agent': 'azsdk-python-storage-blob/12.19.0 Python/3.10.11 (Windows-10-10.0.22631-SP0)'
    'x-ms-date': 'Fri, 19 Jan 2024 19:25:53 GMT'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'Authorization': '*****'
Request body:
b"Hello there, Azure Storage. I'm a friendly file ready to be stored in a blob."
Response status: 201
Response headers:
    'Content-Length': '0'
    'Content-MD5': 'SUytm0872jZh+KYqtgjbTA=='
    'Last-Modified': 'Fri, 19 Jan 2024 19:25:54 GMT'
    'ETag': '"0x8DC1924749AE3C3"'
    'Server': 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0'
    'x-ms-request-id': '7ac499fa-601e-006d-3f0d-4bdf28000000'
    'x-ms-client-request-id': '8f7b1b0b-b700-11ee-b391-782b46f5c56b'
    'x-ms-version': '2023-11-03'
    'x-ms-content-crc64': 'rtHLUlztgxc='
    'x-ms-request-server-encrypted': 'true'
    'Date': 'Fri, 19 Jan 2024 19:25:53 GMT'
Response content:
b''

注意

如果您收到授權錯誤，請確定您執行的身分識別已獲指派 Blob 容器上的「記憶體 Blob 數據參與者」角色。若要深入瞭解，請參閱從應用程式程式代碼使用 Blob 記憶體（無密碼索引標籤）。

共用方式為

在適用於 Python 的 Azure 連結庫中設定記錄

設定記錄層級

連結庫特定的記錄層級行為

註冊記錄數據流處理程式

啟用客戶端物件或作業的 HTTP 記錄

開啟客戶端物件的 HTTP 記錄（DEBUG 層級）

開啟認證物件的 HTTP 記錄（DEBUG 層級）

開啟個別方法的記錄功能（DEBUG 層級）

記錄輸出範例

意見反應

其他資源

共用方式為

在適用於 Python 的 Azure 連結庫中設定記錄

設定記錄層級

連結庫特定的記錄層級行為

註冊記錄數據流處理程式

啟用客戶端物件或作業的 HTTP 記錄

開啟客戶端物件的 HTTP 記錄 （DEBUG 層級）

開啟認證物件的 HTTP 記錄 （DEBUG 層級）

開啟個別方法的記錄功能 （DEBUG 層級）

記錄輸出範例

意見反應

其他資源

開啟客戶端物件的 HTTP 記錄（DEBUG 層級）

開啟認證物件的 HTTP 記錄（DEBUG 層級）

開啟個別方法的記錄功能（DEBUG 層級）