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 애플리케이션에서 복구할 가능성이 없는 오류입니다(예: 메모리 부족).
로깅. WARNING(기본값) 함수가 의도한 작업을 수행하지 못합니다(REST API 호출 다시 시도와 같이 함수가 복구할 수 있는 경우는 아님). 함수는 일반적으로 예외를 발생시키는 경우 경고를 기록합니다. 경고 수준은 자동으로 오류 수준을 사용하도록 설정합니다.
logging.INFO 함수가 정상적으로 작동하거나 서비스 호출이 취소됩니다. 정보 이벤트에는 일반적으로 요청, 응답 및 헤더가 포함됩니다. 정보 수준은 오류 및 경고 수준을 자동으로 사용하도록 설정합니다.
로깅. 디버그 문제 해결에 일반적으로 사용되며 예외에 대한 스택 추적을 포함하는 세부 정보입니다. 디버그 수준은 정보, 경고 및 오류 수준을 자동으로 사용하도록 설정합니다. 주의: 또한 설정하는 logging_enable=True경우 디버그 수준에는 헤더의 계정 키 및 기타 자격 증명과 같은 중요한 정보가 포함됩니다. 보안이 손상되지 않도록 이러한 로그를 보호해야 합니다.
logging.NOTSET 모든 로깅을 사용하지 않도록 설정합니다.

라이브러리별 로깅 수준 동작

각 수준의 정확한 로깅 동작은 해당 라이브러리에 따라 달라집니다. azure.eventhub와 같은 일부 라이브러리는 광범위한 로깅을 수행하는 반면 다른 라이브러리는 거의 수행하지 않습니다.

라이브러리에 대한 정확한 로깅을 검사하는 가장 좋은 방법은 Python 소스 코드용 Azure SDK에서 로깅 수준을 검색하는 것입니다.

  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 정보가 포함되지 않습니다. 로그 출력(DEBUG 수준)에 HTTP 정보를 포함하려면 클라이언트 또는 자격 증명 개체 생성자 또는 특정 메서드에 명시적으로 전달 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''

참고 항목

권한 부여 오류가 발생하면 실행 중인 ID에 Blob 컨테이너에 "Storage Blob 데이터 기여자" 역할이 할당되어 있는지 확인합니다. 자세한 내용은 인증과 함께 Blob Storage 사용을 참조하세요.