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 al usar el SDK de Azure para Java y vínculos a otros artículos con más detalles.

El SDK de Azure para Java consta de muchas bibliotecas cliente: uno o varios para cada servicio Azure que existe. Microsoft garantiza 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, Microsoft desarrolló 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 SDK de Azure 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, Microsoft también proporciona guías de solución de problemas específicas de la biblioteca. Actualmente, están disponibles las siguientes guías:

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, habilite 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 el SDK de Azure para Java.

Habilitar el registro de solicitud y respuesta HTTP

Al solucionar problemas, revise las solicitudes HTTP a medida que se envían y reciben entre los servicios de Azure. Para habilitar el registro de la carga útil de las solicitudes y respuestas HTTP, configure casi todas las bibliotecas cliente del SDK de Azure para Java en sus generadores de clientes, como se muestra en el siguiente ejemplo. En concreto, preste atención especialmente al método httpLogOptions en el generador de clientes y a 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 la solicitud HTTP y el registro de respuesta 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. Este cambio habilita el registro para cada cliente de Azure que admite el registro de solicitudes y respuestas HTTP.

Importancia Nivel de registro
none El registro de solicitudes y respuestas HTTP está deshabilitado.
basic Registra solo direcciones URL, métodos HTTP y el tiempo para finalizar la solicitud.
headers Registra todo en BASIC, además de todas las cabeceras de las solicitudes y las respuestas.
body Registra todo en BASIC, además de los cuerpos de la solicitud y de la respuesta.
body_and_headers Registra todo en CABECERAS y el CUERPO.

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. Puede agregar parámetros y encabezados de consulta 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 del SDK de Azure para Java lanzan una excepción HttpResponseException o una subclase más específica si se produce un 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 en la propiedad de mensaje del objeto HttpResponseException. Dado que estas excepciones son excepciones de ejecución, la documentación de referencia de JavaDoc no las menciona 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 capturar y controlar excepciones en las devoluciones de llamada con errores, 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 en la nube.

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

Pasos siguientes

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

  • Last updated on