Configuración del registro en el SDK de Azure para Java

En este artículo se proporciona información general sobre cómo habilitar el registro en aplicaciones que usan el SDK de Azure para Java. Las bibliotecas cliente de Azure para Java ofrecen dos opciones de registro:

• Una plataforma de registro integrada para depuraciones temporales
• Compatibilidad con el registro mediante la interfaz SLF4J .

Use SLF4J porque es conocido en el ecosistema de Java y está bien documentado. Para obtener más información, consulte los manuales de instrucción de SLF4J.

En este artículo se incluyen vínculos a otros artículos que abarcan muchos de los conocidos marcos de registro de Java. En estos otros artículos se proporcionan ejemplos de configuración y se describe cómo las bibliotecas cliente de Azure pueden usar los marcos de registro.

Independientemente de la configuración de registro que utilice, obtendrá la misma salida de registro porque toda la salida de registro de las bibliotecas cliente de Azure para Java se enruta a través de una abstracción de azure-core ClientLogger.

El resto de este artículo detalla la configuración de todas las opciones de registro disponibles.

Habilitación del registro de solicitudes y respuestas HTTP

El registro de solicitudes y respuestas HTTP está desactivado de forma predeterminada. Puede configurar los clientes que se comunican con los servicios de Azure a través de HTTP para escribir un registro de registro para cada solicitud y respuesta (o excepción) que reciben.

Si usa OpenTelemetry, considere la posibilidad de usar el seguimiento distribuido en lugar de registrar las solicitudes HTTP. Para más información, consulte Configuración del seguimiento en el SDK de Azure para Java.

Configuración del registro HTTP con una variable de entorno

Use la variable de entorno AZURE_HTTP_LOG_DETAIL_LEVEL para activar los registros HTTP para todos los clientes. Establezca esta variable en uno de los siguientes valores:

• NONE: los registros HTTP están desactivados. Este valor es el valor predeterminado.
• BASIC: los registros HTTP incluyen el método de solicitud, la dirección URL de solicitud saneada, el recuento de intentos, el código de respuesta y la longitud del contenido de los cuerpos de solicitud y respuesta.
• HEADERS: los registros HTTP incluyen todos los detalles básicos y también incluyen encabezados que se sabe que son seguros con fines de registro; es decir, no contienen secretos ni información confidencial. La lista completa de nombres de encabezado está disponible en la clase HttpLogOptions .
• BODY_AND_HEADERS: los registros HTTP incluyen todos los detalles proporcionados por el HEADERS nivel e incluyen también cuerpos de solicitud y respuesta siempre que sean menores de 16 KB e imprimibles.

Por ejemplo, la dirección URL de firma de acceso compartido (SAS) de Azure Blob Storage se registra en el formato siguiente: https://myaccount.blob.core.windows.net/pictures/profile.jpg?sv=REDACTED&st=REDACTED&se=REDACTED&sr=REDACTED&sp=REDACTED&rscd=REDACTED&rsct=REDACTED&sig=REDACTED

Configuración del registro HTTP en código

Los generadores de cliente de Azure que implementan la interfaz HttpTrait<T> admiten la configuración de registro HTTP basada en código. La configuración basada en código se aplica a instancias de cliente individuales y proporciona más opciones y personalizaciones en comparación con la configuración de variables de entorno.

Para configurar los registros, pase una instancia de HttpLogOptions al httpLogOptions método en el generador de clientes correspondiente. En el código siguiente se muestra un ejemplo del servicio App Configuration:

HttpLogOptions httpLogOptions = new HttpLogOptions()
        .setLogLevel(HttpLogDetailLevel.HEADERS)
        .addAllowedHeaderName("Accept-Ranges")
        .addAllowedQueryParamName("label");

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .httpLogOptions(httpLogOptions)
        ...
        .buildClient();

Este código habilita los registros HTTP con encabezados y agrega el Accept-Ranges encabezado de respuesta y el label parámetro de consulta a las listas de permitidos correspondientes. Después de este cambio, estos valores aparecen en los registros generados.

Para obtener la lista completa de opciones de configuración, consulte la documentación de HttpLogOptions .

Registrador predeterminado (para la depuración temporal)

Como se indicó, todas las bibliotecas cliente de Azure usan SLF4J para el registro de logs, pero hay un registrador predeterminado y de respaldo integrado en las bibliotecas cliente de Azure para Java. Este registrador predeterminado es para los casos en los que se implementa una aplicación y se necesita el registro, pero no se puede volver a implementar la aplicación con un registrador SLF4J incluido. Para habilitar este registrador, asegúrese primero de que no exista ningún registrador SLF4J (porque tiene prioridad) y, a continuación, establezca la AZURE_LOG_LEVEL variable de entorno. En la tabla siguiente se muestran los valores permitidos para esta variable de entorno:

Después de establecer la variable de entorno, reinicie la aplicación para habilitar la variable de entorno. Este registrador efectuará el registro en la consola; no ofrece las posibilidades de personalización avanzada de una implementación de SLF4J, como la sustitución y el registro en un archivo. Para desactivar el registro, quite la variable de entorno y reinicie la aplicación.

Registro del SLF4J

De forma predeterminada, configure el registro mediante un marco de registro compatible con SLF4J. En primer lugar, incluya una implementación de registro de SLF4J pertinente como una dependencia del proyecto. Para obtener más información, consulte Declaración de dependencias del proyecto para iniciar sesión en el manual de instrucciones de SLF4J. A continuación, configure el registrador para que funcione según sea necesario en su entorno, como establecer niveles de registro, configurar qué clases hacen y no registran, etc. Algunos ejemplos se proporcionan a través de los vínculos de este artículo, pero para obtener más información, consulte la documentación del marco de registro elegido.

Formato de registro

Los marcos de registro admiten diseños y formatos de mensajes de registro personalizados. Incluya al menos los siguientes campos para que sea posible solucionar problemas de Azure bibliotecas cliente:

• Fecha y hora con precisión de milisegundos
• Gravedad del registro
• Nombre del registrador
• Nombre del hilo
• Mensaje

Para obtener ejemplos, consulte la documentación del marco de registro que usa.

Registro estructurado

Además de registrar las propiedades comunes mencionadas anteriormente, las bibliotecas cliente de Azure anotan los mensajes de registro con contexto adicional cuando corresponda. Por ejemplo, es posible que haya registros con formato JSON que contienen az.sdk.message con contexto escrito como otras propiedades raíz, tal y como se muestra en el siguiente ejemplo:

16:58:51.038 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP request","method":"GET","url":"<>","tryCount":"1","contentLength":0}
16:58:51.141 INFO  c.a.c.c.i.C.getManifestProperties - {"az.sdk.message":"HTTP response","contentLength":"558","statusCode":200,"url":"<>","durationMs":102}

Al enviar registros a Azure Monitor, puede usar el lenguaje de consulta Kusto para analizarlos. La consulta siguiente proporciona un ejemplo:

traces
| where message startswith "{\"az.sdk.message"
| project timestamp, logger=customDimensions["LoggerName"], level=customDimensions["LoggingLevel"], thread=customDimensions["ThreadName"], azSdkContext=parse_json(message)
| evaluate bag_unpack(azSdkContext)

Pasos siguientes

Ahora que sabe cómo funciona el registro en El SDK de Azure para Java, considere la posibilidad de revisar los siguientes artículos. En estos artículos se proporcionan instrucciones sobre cómo configurar algunos de los marcos de registro de Java más populares para trabajar con SLF4J y las bibliotecas cliente de Java:

• java.util.logging
• Logback
• Log4J
• Seguimiento