Share via

Configuración del registro en Azure SDK para Java

  • Artículo

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

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

Se recomienda usar SLF4J porque es muy conocido en el ecosistema de Java y está bien documentado. Para más información, consulte Manual de usuario de SLF4J.

En este artículo se incluyen vínculos a otros artículos que cubren muchas de las plataformas de registro de Java más populares. En esos artículos se ofrecen ejemplos de configuración y se describe cómo las bibliotecas cliente de Azure pueden usar las plataformas de registro.

Sea cual sea la configuración de registro que use, dispondrá de la misma salida del registro, porque todas las salidas de registro de las bibliotecas cliente de Azure para Java se enrutan por medio de una abstracción ClientLogger de azure-core.

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

Habilitar el registro de solicitud y respuesta 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

Puede usar la AZURE_HTTP_LOG_DETAIL_LEVEL variable de entorno para habilitar los registros HTTP globalmente. Esta variable admite los siguientes valores:

  • NONE: los registros HTTP están deshabilitados. Este es el valor predeterminado.
  • BASIC: los registros HTTP contienen 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.

Nota:

La dirección URL de la solicitud está saneada; es decir, todos los valores de los parámetros de consulta se redactan excepto el api-version valor. Las bibliotecas cliente individuales pueden agregar otros parámetros de consulta que se sabe que son seguros para la lista de permitidos.

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

Advertencia

No se recomienda registrar cuerpos de solicitud y respuesta en producción porque pueden contener información confidencial, afectar significativamente al rendimiento, cambiar cómo se almacena en búfer el contenido y tener otros efectos secundarios.

Configuración del registro HTTP en el 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 deben aparecer 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, pero hay un registrador predeterminado de reserva integrado en las bibliotecas cliente de Azure para Java. Este registrador predeterminado se proporciona para los casos en los que se implementa una aplicación y se requiere el registro, pero no es posible volver a implementar la aplicación con un registrador SLF4J incluido. Para habilitar este registrador, primero debe estar seguro de que no existe ningún registrador de SLF4J (porque tiene prioridad) y, a continuación, establecer la AZURE_LOG_LEVEL variable de entorno. En la tabla siguiente se muestran los valores permitidos para esta variable de entorno:

Nivel de registro Valores permitidos de la variable de entorno
VERBOSE verbose, debug
INFORMATIONAL info, , information, informational
ADVERTENCIA warn, warning
ERROR err, error

Después de establecer la variable de entorno, reinicie la aplicación para que la variable de entorno surta efecto. Este registrador registra en la consola y no proporciona las funcionalidades de personalización avanzadas de una implementación de SLF4J, como la sustitución y el registro en el archivo. Para volver a desactivar el registro, solo tiene que quitar la variable de entorno y reiniciar la aplicación.

Registro de SLF4J

De forma predeterminada, debe configurar el registro mediante una plataforma de registro compatible con SLF4J. En primer lugar, incluya la implementación de registro de SLF4J correspondiente como una dependencia del proyecto. Para obtener más información, consulte la sección sobre declaración de las dependencias del proyecto para el registro en el manual del usuario 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. Se recomienda incluir al menos campos siguientes para que sea posible solucionar problemas de bibliotecas cliente de Azure:

  • Fecha y hora con precisión de milisegundos
  • Gravedad del registro
  • Nombre del registrador
  • Nombre del subproceso
  • 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 vea registros con formato JSON que contienen az.sdk.message el contexto escrito como otras propiedades raíz, como se muestra en el ejemplo siguiente:

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)

Nota:

Los registros de la biblioteca cliente de Azure están diseñados para la depuración ad hoc. No se recomienda confiar en el formato de registro para alertar o supervisar la aplicación. Las bibliotecas cliente de Azure no garantizan la estabilidad de los mensajes de registro ni las claves de contexto. Para tales fines, se recomienda usar el seguimiento distribuido. El agente de Java de Application Ideas proporciona garantías de estabilidad para la telemetría de solicitudes y dependencias. Para más información, consulte Configuración del seguimiento en el SDK de Azure para Java.

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: