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:
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=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:
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.
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 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)
Sepa cómo capturar resultados de seguimiento de las aplicaciones web de Azure. Vea una secuencia de registro en vivo y descargue archivos de registro para realizar análisis sin conexión.