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 ライブラリでのこれらのログ レベルの一般的な使用方法について説明します。

ライブラリ固有のログ レベルの動作

各レベルでの正確なログ動作は、該当するライブラリによって異なります。 azure.eventhub などの一部のライブラリでは、広範なログが実行されますが、他のライブラリではほとんど実行されません。

ライブラリの正確なログを確認する最善の方法は、Azure SDK for Python のソース コードでログ レベルを検索することです。

1. リポジトリ フォルダーで、sdk フォルダーに移動し、目的の特定のサービスのフォルダーに移動します。

2. そのフォルダーで、次の文字列のいずれかを検索します。

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

ログ ストリーム ハンドラーを登録する

ログ出力をキャプチャするには、コードに少なくとも 1 つのログ ストリーム ハンドラーを登録する必要があります。

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 ログを有効にする (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''