Compartir a través de

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:

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:

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

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

Importancia Nivel de registro
none El registro de solicitudes/respuestas HTTP está deshabilitado.
basic Registra solo direcciones URL, métodos HTTP y el tiempo para finalizar la solicitud.
headers Registra todo en BÁSICO, además de todos los encabezados de solicitud y respuesta.
body Registra todo en BÁSICO, además de todo el cuerpo de solicitud y respuesta.
body_and_headers Registra todo en ENCABEZADOS y 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. 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 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 Azure SDK para Java, consulte Configuración del seguimiento en Azure SDK para Java.

Pasos siguientes

Si la guía de resolución de problemas de este artículo no le ayuda a resolver los problemas al usar bibliotecas cliente de Azure SDK para Java, le recomendamos que deje la incidencia en el repositorio GitHub de Azure SDK para Java.