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

發行項
11/14/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 資訊，您必須明確傳遞 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 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 記憶體（無密碼索引標籤）。

共用方式為