Configuración del registro en las bibliotecas de Azure para Python
Las bibliotecas de Azure para Python basadas en azure.core proporcionan resultados de registro mediante la biblioteca de registro estándar de Python.
Este es el proceso general para trabajar con el registro:
- Adquiera el objeto de registro de la biblioteca deseada y establezca el nivel de registro.
- Registre un controlador para el flujo de registro.
- Para incluir información de HTTP, pase un parámetro
logging_enable=Truea 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.resourcey, a continuación, se establece el nivel de registro enlogging.DEBUG. - Puede llamar a
logger.setLevelen 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 usan el azure registrador 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 establece logging_enable=True, el nivel de depuración incluye información confidencial, como 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 extenso, mientras que otras bibliotecas no lo hacen.
La mejor manera de examinar el registro exacto de una biblioteca es buscar los niveles de registro en el código fuente de Azure SDK para Python:
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.
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 HTTP. Para incluir información HTTP en la salida del registro (como nivel DEBUG), debe pasar logging_enable=True explícitamente a un constructor de objeto de cliente o credencial o a un método específico.
Precaución
El registro HTTP puede incluir información confidencial, como 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 (nivel de depuración)
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 (nivel de depuración)
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 para todas las operaciones invocadas a través de ese objeto, pero no para las operaciones de un objeto cliente que no implican autenticación.
Habilitación del registro para un método individual (nivel de depuración)
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 recibe un error de autorización, asegúrese de que a la identidad en la que se ejecuta se le asigna el rol "Colaborador de datos de Storage Blob" en el contenedor de blobs. Para más información, consulte Uso de Blob Storage con autenticación.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de