Python 用 Azure ライブラリにログを構成する

[アーティクル]
01/29/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.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 のソースコードでログレベルを検索することです。

リポジトリフォルダーで、sdk フォルダーに移動し、目的の特定のサービスのフォルダーに移動します。
そのフォルダーで、次の文字列のいずれかを検索します。
- _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 ログには、ヘッダー内のアカウントキーやその他の資格情報などの機密情報が含まれている場合があります。セキュリティ侵害を避けるため、これらのログは必ず保護するようにしてください。

クライアントオブジェクトの 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''

Note

承認エラーが発生した場合は、実行している ID に BLOB コンテナの "ストレージ BLOB データ共同作成者" ロールが割り当てられていることを確認してください。詳細については、「アプリコードから Blob Storage を使用する」を参照してください。

次の方法で共有

Python 用 Azure ライブラリにログを構成する

ログレベルの設定

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

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

クライアントオブジェクトまたは操作の HTTP ログを有効にする

クライアントオブジェクトの HTTP ログを有効にする (DEBUG レベル)

資格情報オブジェクトの HTTP ログを有効にする (DEBUG レベル)

個々のメソッドのログを有効にする (DEBUG レベル)

ログ出力の例

フィードバック

その他のリソース

次の方法で共有

Python 用 Azure ライブラリにログを構成する

ログ レベルの設定

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

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

クライアント オブジェクトまたは操作の HTTP ログを有効にする

クライアント オブジェクトの HTTP ログを有効にする (DEBUG レベル)

資格情報オブジェクトの HTTP ログを有効にする (DEBUG レベル)

個々のメソッドのログを有効にする (DEBUG レベル)

ログ出力の例

フィードバック

その他のリソース

ログレベルの設定

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

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

クライアントオブジェクトまたは操作の HTTP ログを有効にする

クライアントオブジェクトの HTTP ログを有効にする (DEBUG レベル)