Настройка ведения журнала в библиотеках Azure для Python

Библиотеки Azure для Python, основанные на azure.core, предоставляют выходные данные ведения журнала с помощью стандартной библиотеки ведения журналов Python.

Общий процесс работы с ведением журнала выглядит следующим образом:

1. Получите объект ведения журнала для нужной библиотеки и установите уровень ведения журнала.
2. Зарегистрируйте обработчик для потока ведения журнала.
3. Чтобы добавить данные HTTP, передайте параметр logging_enable=True в конструктор клиентского объекта, конструктор объекта учетных данных или в конкретный метод.

Подробные сведения приведены в остальных разделах этой статьи.

Обычно, чтобы разобраться в использовании ведения журнала в библиотеках, лучше всего просто изучить исходный код пакета SDK, который доступен по адресу github.com/Azure/azure-sdk-for-python. Мы рекомендуем клонировать этот репозиторий на локальный компьютер, чтобы легко найти нужные данные, когда потребуется (например, при работе со следующими разделами).

Настройка уровней ведения журнала

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

Уровни ведения журнала совпадают со стандартными уровнями библиотеки ведения журнала. В следующей таблице собраны общие сведения об использовании этих уровней ведения журнала в библиотеках Azure для Python:

Уровень ведения журнала	Типичное использование
logging.ERROR;	Сбои, после которых приложение вряд ли восстановится (например, недостаточно памяти).
logging.WARNING (уровень по умолчанию)	Функция не может выполнить поставленную задачу (но не в тех случаях, когда эта функция может восстановить работу самостоятельно, как, например, при повторах вызова REST API). Функции обычно заносят предупреждение в журнал при создании исключений. Уровень предупреждений автоматически включает уровень ошибок.
logging.INFO	Функция работает нормально или отменен вызов службы. Информационные события обычно содержат запросы, ответы и заголовки. Уровень информационных сообщений автоматически включает уровни ошибок и предупреждений.
logging.DEBUG	Подробные сведения, которые могут помочь при устранении неполадок и содержат трассировку стека для исключений. Уровень отладки автоматически включает уровни информационных сведений, предупреждений и ошибок. ВНИМАНИЕ. Если вы также установили logging_enable=True, уровень отладки включает конфиденциальные сведения, такие как ключи учетной записи в заголовках и других учетных данных. Убедитесь, что эти журналы защищены, чтобы избежать нарушения безопасности.
logging.NOTSET	Ведение журнала отключено.

Поведение уровней ведения журнала для конкретных библиотек

Точное поведение на каждом уровне ведения журнала зависит от конкретной библиотеки. Некоторые библиотеки, такие как azure.eventhub, выполняют обширное ведение журнала, а другие библиотеки делают мало.

Лучший способ проверить точное ведение журнала для библиотеки — найти уровни ведения журнала в исходном коде Azure SDK для Python:

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. Вы можете использовать и другие типы обработчиков, как описано в разделе logging.handlers в документации по Python, или стандартный метод logging.basicConfig.

Включение ведения журнала на основе данных HTTP для клиентского объекта или операции

По умолчанию ведение журнала в библиотеках Azure не содержит никаких данных HTTP. Чтобы включить данные 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)

Пример выходных данных журнала

Следующий код показан в примере использования учетной записи хранения с включением функций ведения журнала HTTP и DEBUG:

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-объектов с проверкой подлинности".