Compartir vía

Configuración del registro en las bibliotecas de Azure para Python

  • Artículo

Las bibliotecas de Azure para Python que están basadas en azure.core proporcionan la salida del registro mediante la biblioteca de registro de Python estándar.

Este es el proceso general para trabajar con el registro:

  1. Adquiera el objeto de registro de la biblioteca deseada y establezca el nivel de registro.
  2. Registre un controlador para el flujo de registro.
  3. Para incluir información de HTTP, pase un parámetro logging_enable=True a un constructor de objetos de cliente, un constructor de objetos de credencial o un método específico.

En las restantes secciones del artículo encontrará más información al respecto.

Como norma general, el mejor recurso para comprender el uso del registro dentro de las bibliotecas es examinar el código fuente del SDK en github.com/Azure/azure-sdk-for-python. Se recomienda clonar este repositorio de forma local para que pueda buscar fácilmente los detalles cuando sea necesario, como se sugiere en las siguientes secciones.

Establecimiento de los niveles de registro

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)
  • En este ejemplo se adquiere el registrador de la biblioteca azure.mgmt.resource y, a continuación, se establece el nivel de registro en logging.DEBUG.
  • Puede llamar a logger.setLevel en cualquier momento para cambiar el nivel de registro de los distintos segmentos de código.

Para establecer un nivel para una biblioteca diferente, utilice el nombre de esa biblioteca en la llamada a logging.getLogger. Por ejemplo, la biblioteca azure-eventhubs proporciona un registrador llamado azure.eventhubs, la biblioteca azure-storage-queue proporciona un registrador llamado azure.storage.queue, etc. (El código fuente del SDK usa con frecuencia la instrucción logging.getLogger(__name__), que adquiere un registrador con el nombre del módulo contenedor).

También puede utilizar espacios de nombres más generales. Por ejemplo,

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)

Algunas bibliotecas utilizan el registrador azure en lugar de un registrador específico. Por ejemplo, la biblioteca azure-storage-blob usa el registrador azure.

puede usar el método logger.isEnabledFor para comprobar si está habilitado un nivel de registro determinado:

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

Los niveles de registro son los mismos que los niveles de la biblioteca de registro estándar. En la tabla siguiente se describe el uso general de estos niveles de registro en las bibliotecas de Azure para Python:

Nivel de registro Uso típico
logging.ERROR Errores en los que no es probable que la aplicación se recupere (por ejemplo, memoria insuficiente).
logging.WARNING (predeterminado) Una función no puede realizar la tarea deseada (pero no cuando la función se puede recuperar, como al volver a intentar una llamada a la API REST). Normalmente, las funciones registran una advertencia al generar excepciones. El nivel de advertencia habilita automáticamente el nivel de error.
logging.INFO La función opera con normalidad o se cancela una llamada de servicio. Los eventos de información suelen incluir solicitudes, respuestas y encabezados. El nivel de información habilita automáticamente los niveles de error y de advertencia.
logging.DEBUG Información detallada que se usa normalmente para solucionar problemas e incluye un seguimiento de la pila para las excepciones. El nivel de depuración habilita automáticamente los niveles de información, de advertencia y de error. PRECAUCIÓN: Si también se establece logging_enable=True, el nivel de depuración incluye información confidencial, como las claves de cuenta, en encabezados y otras credenciales. Asegúrese de proteger estos registros para evitar poner en peligro la seguridad.
logging.NOTSET Deshabilita todos los registros.

Comportamiento del nivel de registro específico de la biblioteca

El comportamiento de registro exacto en cada nivel depende de la biblioteca en cuestión. Algunas bibliotecas, como azure.eventhub, realizan un registro extensivo, mientras que otras registran muy poco.

La mejor manera de examinar el registro exacto de una biblioteca es buscar los niveles de registro en el código fuente del SDK de Azure para Python:

  1. En la carpeta del repositorio, vaya a la carpeta sdk y, a continuación, vaya a la carpeta del servicio específico de su interés.

  2. En esa carpeta, busque cualquiera de las siguientes cadenas:

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

Registro de un controlador del flujo de registros

Para capturar la salida del registro, debe registrar al menos un controlador del flujo de registros en el código:

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)

En este ejemplo se registra un controlador que dirige la salida del registro a stdout. Puede usar otros tipos de controladores, como se describe en logging.handlers en la documentación de Python, o bien usar el método logging.basicConfig.

Habilitación del registro HTTP para un objeto o una operación de cliente

De forma predeterminada, el registro en las bibliotecas de Azure no incluye información de HTTP. Para incluir información HTTP en la salida del registro, debe pasar logging_enable=True explícitamente a un constructor de objetos de cliente o credencial o a un método específico.

Precaución

El registro HTTP puede incluir información confidencial, como las claves de cuenta, en encabezados y otras credenciales. Asegúrese de proteger estos registros para evitar poner en peligro la seguridad.

Habilitación del registro HTTP para un objeto de cliente

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)

La habilitación del registro HTTP para un objeto de cliente habilita el registro de todas las operaciones invocadas mediante ese objeto.

Habilitación del registro HTTP para un objeto de credencial

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)

Al habilitar el registro HTTP para un objeto de credencial, se habilita el registro de todas las operaciones invocadas a través de ese objeto, pero no de las operaciones de un objeto de cliente que no impliquen la autenticación.

Habilitación del registro para un método individual

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)

Ejemplo de salida del registro

El siguiente código es el que se muestra en Ejemplo: Uso de una cuenta de almacenamiento, al que se ha agregado la habilitación del registro de DEBUG y 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)

La salida es como sigue:

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''

Nota:

Si obtiene un error de autorización, asegúrese de que la identidad con la que se está ejecutando tiene asignada la función "Colaborador de datos de blob de almacenamiento" en su contenedor de blob. Para obtener más información, consulte Uso del almacenamiento blob desde el código de la aplicación (pestaña Sin contraseña).