Configuración del registro en Azure SDK para Java
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.
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 ha implementado una aplicación y se precisa el registro, pero no es posible volver a implementar la aplicación con un registrador de SLF4J incluido. Para habilitar este registrador, primero debe confirmar que no hay registrador de SLF4J (ya que tendría prioridad) y, a continuación, establecer la variable de entorno AZURE_LOG_LEVEL. 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" |
| WARNING | "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 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, 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. En los vínculos siguientes se proporcionan algunos ejemplos. Para obtener más detalles, consulte la documentación de la plataforma de registro elegida.
Formato de registro
Los marcos de registro admiten diseños y formatos de mensajes de registro personalizados. Se recomienda incluir al menos los siguientes campos 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
- Message
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, puede ver registros con formato JSON que contienen az.sdk.message con 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 estos 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 ha visto cómo funciona el registro en Azure SDK para Java, quizá le interese revisar los vínculos siguientes para obtener instrucciones sobre cómo configurar algunas de las plataformas de registro de Java más populares para trabajar con SLF4J y las bibliotecas cliente de Java: