Compartir vía

Solución de problemas de Azure Event Hubs

  • Artículo

En este artículo se tratan las técnicas de investigación de errores, los errores comunes para los tipos de credenciales de la biblioteca de Event Hubs y los pasos de mitigación para resolver estos errores. Además de las técnicas generales de solución de problemas e instrucciones que se aplican independientemente del caso de uso de Event Hubs, en los siguientes artículos se tratan características específicas de la biblioteca de Event Hubs:

En el resto de este artículo se tratan las técnicas generales de solución de problemas y las instrucciones que se aplican a todos los usuarios de la biblioteca de Event Hubs.

Control de excepciones de Event Hubs

Todas las excepciones de Event Hubs se encapsulan en amqpException. Estas excepciones suelen tener un código de error AMQP subyacente que especifica si se debe reintentar un error. Para los errores reintentos (es decir, amqp:connection:forced o amqp:link:detach-forced), las bibliotecas cliente intentan recuperarse de estos errores en función de las opciones de reintento especificadas al crear instancias del cliente. Para configurar las opciones de reintento, siga los eventos de publicación de ejemplo en una partición específica. Si el error no es irrecuperable, hay algún problema de configuración que debe resolverse.

La manera recomendada de resolver la excepción específica que representa la excepción AMQP es seguir las instrucciones de excepciones de mensajería de Event Hubs .

Búsqueda de información relevante en mensajes de excepción

AmqpException contiene los tres campos siguientes, que describen el error:

  • getErrorCondition: error de AMQP subyacente. Para obtener una descripción de los errores, consulte la documentación de Enumeración AmqpErrorCondition o la especificación DE OASIS AMQP 1.0.
  • isTransient: valor que indica si es posible intentar realizar la misma operación. Los clientes del SDK aplican la directiva de reintento cuando el error es transitorio.
  • getErrorContext: contiene la siguiente información sobre dónde se originó el error AMQP:

Excepciones frecuentemente encontradas

amqp:connection:forced y amqp:link:detach-forced

Cuando la conexión a Event Hubs está inactiva, el servicio desconecta el cliente después de algún tiempo. Este problema no es un problema porque los clientes vuelven a establecer una conexión cuando se solicita una operación de servicio. Para más información, consulte Errores de AMQP en Azure Service Bus.

Problemas de permisos

Un AmqpException con amqpErrorCondition de amqp:unauthorized-access significa que las credenciales proporcionadas no permiten realizar la acción (recepción o envío) con Event Hubs. Para resolver este problema, pruebe las siguientes tareas:

Para ver otras posibles soluciones, consulte Solución de problemas de autenticación y autorización con Event Hubs.

Problemas de conectividad

Tiempo de espera al conectarse al servicio

Para resolver problemas de tiempo de espera, pruebe las siguientes tareas:

Errores de protocolo de enlace TLS/SSL

Este error puede producirse cuando se usa un proxy de interceptación. Para comprobarlo, se recomienda probar en el entorno de hospedaje con el proxy deshabilitado.

Errores de agotamiento de sockets

Las aplicaciones deben preferir tratar a los clientes de Event Hubs como singleton, crear y usar una sola instancia a través de la duración de su aplicación. Esta recomendación es importante porque cada tipo de cliente administra su conexión. Cuando se crea un nuevo cliente de Event Hubs, se produce una nueva conexión AMQP, que usa un socket. Además, es esencial que los clientes hereden de java.io.Closeable, por lo que la aplicación es responsable de llamar close() cuando haya terminado de usar un cliente.

Para usar la misma conexión AMQP al crear varios clientes, puede usar la EventHubClientBuilder.shareConnection() marca , contener una referencia a ese EventHubClientBuildery crear nuevos clientes a partir de esa misma instancia del generador.

Conectar mediante una cadena de conexión de IoT

Dado que la traducción de un cadena de conexión requiere consultar el servicio IoT Hub, la biblioteca cliente de Event Hubs no puede usarla directamente. En el ejemplo ioT Conectar ionString.java se describe cómo consultar IoT Hub para traducir una cadena de conexión de IoT en una que se pueda usar con Event Hubs.

Para más información, consulte los siguientes artículos.

No se pueden agregar componentes al cadena de conexión

Los clientes heredados de Event Hubs permitían a los clientes agregar componentes al cadena de conexión recuperado de Azure Portal. Los clientes heredados están en paquetes com.microsoft.azure:azure-eventhubs y com.microsoft.azure:azure-eventhubs-eph. La generación actual solo admite cadena de conexión en el formulario publicado por Azure Portal.

Agregar "TransportType=AmqpWebSockets"

Para usar sockets web, consulte el ejemplo PublishEventsWithSocketsAndProxy.java .

Agregar "Authentication=Managed Identity"

Para autenticarse con identidad administrada, consulte el ejemplo PublishEventsWithAzureIdentity.java.

Para más información sobre la Azure.Identity biblioteca, consulte nuestra entrada de blog Autenticación y El SDK de Azure.

Habilitación y configuración del registro

El SDK de Azure para Java ofrece un artículo de registro coherente para ayudar a solucionar errores de aplicación y para ayudar a acelerar su resolución. Los registros generados capturan el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz. Para obtener instrucciones sobre el registro, consulte Configuración del registro en el SDK de Azure para Java y Introducción a la solución de problemas.

Además de habilitar el registro, establezca el nivel VERBOSE de registro en o DEBUG proporcione información sobre el estado de la biblioteca. En las secciones siguientes se muestran configuraciones de log4j2 y logback de ejemplo para reducir los mensajes excesivos cuando se habilita el registro detallado.

Configuración de Log4J 2

Siga estos pasos para configurar Log4J 2:

  1. Agregue las dependencias en pom.xml con las del ejemplo de registro pom.xml, en la sección "Dependencias necesarias para Log4j2".
  2. Agregue log4j2.xml a la carpeta src/main/resources .

Configuración de logback

Siga estos pasos para configurar la devolución de sesión:

  1. Agregue las dependencias en pom.xml con las del ejemplo de registro pom.xml, en la sección "Dependencias necesarias para la devolución de sesión".
  2. Agregue logback.xml a la carpeta src/main/resources .

Habilitación del registro de transporte de AMQP

Si habilitar el registro de cliente no es suficiente para diagnosticar sus problemas, puede habilitar el registro en un archivo de la biblioteca AMQP subyacente, Qpid Proton-J. Qpid Proton-J usa java.util.logging. Puede habilitar el registro mediante la creación de un archivo de configuración con el contenido que se muestra en la sección siguiente. O bien, establezca proton.trace.level=ALL y las opciones de configuración que desee para la java.util.logging.Handler implementación. Para conocer las clases de implementación y sus opciones, consulte Package java.util.logging en la documentación del SDK de Java 8.

Para realizar un seguimiento de los marcos de transporte de AMQP, establezca la variable de PN_TRACE_FRM=1 entorno.

Archivo "logging.properties" de ejemplo

El siguiente archivo de configuración registra la salida de nivel trace de Proton-J al archivo proton-trace.log :

handlers=java.util.logging.FileHandler
.level=OFF
proton.trace.level=ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=proton-trace.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

Reducción del registro

Una manera de reducir el registro es cambiar el nivel de detalle. Otra manera es agregar filtros que excluyen los registros de los paquetes de nombres de registrador como com.azure.messaging.eventhubs o com.azure.core.amqp. Para obtener ejemplos, consulte los archivos XML en las secciones Configuración de Log4J 2 y Configuración de la devolución de sesión.

Al enviar un error, los mensajes de registro de las clases de los siguientes paquetes son interesantes:

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • La excepción es que puede omitir el onDelivery mensaje en ReceiveLinkHandler.
  • com.azure.messaging.eventhubs.implementation

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.