Introducción a la solución de problemas del SDK de Azure para Java

En este artículo se presentan muchas herramientas de solución de problemas disponibles cuando se usa El SDK de Azure para Java y se vinculan a otros artículos con más detalles.

El SDK de Azure para Java consta de muchas bibliotecas cliente: una o varias para cada servicio de Azure que existe. Nos aseguramos de que todas las bibliotecas cliente se compilan en un estándar coherente y alto, con patrones comunes para la configuración, el registro, el control de excepciones y la solución de problemas. Para más información, consulte Uso del SDK de Azure para Java.

Dado que la solución de problemas puede abarcar un área de temas tan amplia, hemos desarrollado las siguientes guías de solución de problemas que puede que desee revisar:

• Solución de problemas de autenticación de identidad de Azure abarca técnicas de investigación de errores de autenticación, errores comunes para los tipos de credenciales en la biblioteca cliente de Java de identidad de Azure y pasos de mitigación para resolver estos errores.
• Solución de problemas de conflictos de versión de dependencia abarca los temas relacionados con el diagnóstico, mitigación y minimización de conflictos de dependencias. Estos conflictos pueden surgir cuando se usan las bibliotecas cliente de Azure SDK para Java en sistemas creados con herramientas como Maven y Gradle.
• Solución de problemas de red abarca temas relacionados con la depuración HTTP fuera de la biblioteca cliente, mediante herramientas como Fiddler y Wireshark.

Junto con estas guías generales de solución de problemas, también proporcionamos guías de solución de problemas específicas de la biblioteca. En este momento, están disponibles las siguientes guías:

• Solución de problemas de Azure Event Hubs
• Solución de problemas de Azure Service Bus

Además de estos documentos, el siguiente contenido proporciona instrucciones sobre cómo hacer el mejor uso del registro y el control de excepciones en relación con el SDK de Azure para Java.

Uso del registro en el SDK de Azure para Java

En las secciones siguientes se describe cómo habilitar diferentes tipos de registro.

Habilitación del registro de cliente

Para solucionar problemas, es importante habilitar primero el registro para supervisar el comportamiento de la aplicación. Los errores y advertencias de los registros suelen proporcionar información útil sobre lo que ha ido mal y, a veces, incluyen acciones correctivas para corregir problemas. El SDK de Azure para Java tiene compatibilidad completa con el registro. Para más información, consulte Configuración del registro en Azure SDK para Java.

Habilitación del registro de solicitudes y respuestas HTTP

Al solucionar problemas, resulta útil revisar las solicitudes HTTP a medida que se envían y reciben entre los servicios de Azure. Para habilitar el registro de la carga de solicitud y respuesta HTTP, puede configurar casi todas las bibliotecas cliente del SDK de Azure para Java en sus generadores de clientes, como se muestra en el ejemplo siguiente. En concreto, preste especial atención al httpLogOptions método en el generador de clientes y los valores de enumeración disponibles en HttpLogDetailLevel.

ConfigurationClient configurationClient = new ConfigurationClientBuilder()
        .connectionString(connectionString)
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Este código cambia el registro de solicitudes y respuestas HTTP para una sola instancia de cliente. Como alternativa, puede configurar el registro de solicitudes HTTP y respuestas para toda la aplicación estableciendo la AZURE_HTTP_LOG_DETAIL_LEVEL variable de entorno en uno de los valores de la tabla siguiente. Es importante tener en cuenta que este cambio habilita el registro para cada cliente de Azure que admita el registro de solicitudes o respuestas HTTP.

Value	Nivel de registro
none	El registro de solicitudes/respuestas HTTP está deshabilitado.
basic	Registra solo direcciones URL, métodos HTTP y tiempo para finalizar la solicitud.
headers	Registra todo en BASIC, además de todos los encabezados de solicitud y respuesta.
body	Registra todo en BASIC, además de todo el cuerpo de la solicitud y la respuesta.
body_and_headers	Registra todo en HEADERS y BODY.

Nota:

Al registrar los cuerpos de solicitud y respuesta, asegúrese de que no contienen información confidencial. Al registrar los parámetros y encabezados de consulta, la biblioteca cliente tiene un conjunto predeterminado de parámetros de consulta y encabezados que se consideran seguros para registrar. Es posible agregar parámetros de consulta y encabezados adicionales que son seguros para registrar, como se muestra en el ejemplo siguiente:

clientBuilder.httpLogOptions(new HttpLogOptions()
    .addAllowedHeaderName("safe-to-log-header-name")
    .addAllowedQueryParamName("safe-to-log-query-parameter-name"))

Control de excepciones en el SDK de Azure para Java

La mayoría de los métodos de servicio de cliente de Azure SDK para Java inician una excepción HttpResponseException o una subclase más específica en caso de error. El HttpResponseException tipo incluye un objeto de error de respuesta detallado que proporciona información útil específica sobre lo que salió mal e incluye acciones correctivas para corregir problemas comunes. Puede encontrar esta información de error dentro de la propiedad message del HttpResponseException objeto . Dado que estas excepciones son excepciones en tiempo de ejecución, la documentación de referencia de JavaDoc no las llama explícitamente.

En el ejemplo siguiente se muestra cómo detectar esta excepción con un cliente sincrónico:

try {
    ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
    client.getConfigurationSetting(setting);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

Con los clientes asincrónicos, puede detectar y controlar excepciones en las devoluciones de llamada de error, como se muestra en el ejemplo siguiente:

ConfigurationSetting setting = new ConfigurationSetting().setKey("myKey").setValue("myValue");
asyncClient.getConfigurationSetting(setting)
    .doOnSuccess(ignored -> System.out.println("Success!"))
    .doOnError(
        error -> error instanceof ResourceNotFoundException,
        error -> System.out.println("Exception: 'getConfigurationSetting' could not be performed."));

Uso del seguimiento en el SDK de Azure para Java

El SDK de Azure para Java ofrece compatibilidad completa con el seguimiento, lo que le permite ver el flujo de ejecución a través del código de aplicación y las bibliotecas cliente que usa. Puede habilitar el seguimiento en las bibliotecas cliente de Azure mediante y la configuración del SDK de OpenTelemetry o mediante un agente compatible con OpenTelemetry. OpenTelemetry es un conocido marco de observabilidad de código abierto para generar, capturar y recopilar datos de telemetría para software nativo de nube.

Para más información sobre cómo habilitar el seguimiento en Azure SDK para Java, consulte Configuración del seguimiento en Azure SDK para Java.

Pasos siguientes

Si la guía de solución de problemas de este artículo no ayuda a resolver problemas al usar las bibliotecas cliente de Azure SDK para Java, se recomienda presentar un problema en el repositorio de GitHub del SDK de Azure para Java.