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

2025-06-20

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

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.

El resto de este artículo 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 valor 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 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 de logs, pero hay un registrador predeterminado y de respaldo 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 de variables de entorno permitidos
VERBOSO	`verbose`, `debug`
INFORMATIVO	`info`, , `information`, `informational`
Advertencia	`warn`, `warning`
ERROR	`err`, `error`

Una vez establecida la variable de entorno, reinicie la aplicación para permitir que la variable de entorno surta efecto. 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 volver a desactivar el registro, basta con quitar la variable de entorno y reiniciar la aplicación.

Registro del SLF4J

De forma predeterminada, debe configurar 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. 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 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)

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 Insights 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:

Compartir a través de