Solución de problemas de Azure Event Hubs

En este artículo se explica cómo solucionar errores de Azure Event Hubs, incluidos los errores comunes para los tipos de credenciales en la biblioteca de Event Hubs y los pasos de mitigación para resolverlos. 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 una AmqpException. Estas excepciones suelen tener un código de error AMQP subyacente que especifica si se debe reintentar un error. Para los errores reintentables (es decir, amqp:connection:forced o amqp:link:detach-forced), las bibliotecas de cliente intentan recuperarse de estos errores en función de las opciones de reintento especificadas al instanciar el cliente. Para configurar las opciones de reintento, siga el ejemplo publicar eventos 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

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

  • getErrorCondition: el error de AMQP subyacente. Para obtener una descripción de los errores, consulte la documentación de Enumeración AmqpErrorCondition o de la Especificación de AMQP de OASIS 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 comunes de Event Hubs

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 comportamiento no es un problema porque los clientes vuelven a establecer una conexión cuando se solicita una operación de servicio. Para obtener más información, consulte Errores de AMQP en Azure Service Bus.

Resolución de problemas de permisos de Event Hubs

Una AmqpException con una 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 obtener otras soluciones posibles, consulte Solución de problemas de autenticación y autorización con Event Hubs.

Resolución de problemas de conectividad de Event Hubs

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, pruebe en el entorno de hospedaje con el proxy deshabilitado.

Errores de agotamiento de sockets

Tratar los clientes de Event Hubs como una instancia única. Cree y use una sola instancia durante todo el ciclo de vida de la aplicación. Esta recomendación es importante porque cada tipo de cliente administra su conexión. Al crear un nuevo cliente de Event Hubs, se crea 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 a close() cuando haya terminado de usar un cliente.

Para usar la misma conexión AMQP al crear varios clientes, use el indicador EventHubClientBuilder.shareConnection(), mantenga una referencia a ese EventHubClientBuilder y cree nuevos clientes a partir de esa misma instancia del generador.

Conexión mediante una cadena de conexión de IoT

Dado que la traducción de una cadena de conexión requiere consultar el servicio IoT Hub, la biblioteca cliente de Event Hubs no puede usarla directamente. En el ejemplo de IoTConnectionString.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 obtener más información, consulte los artículos siguientes:

No se pueden agregar componentes a la cadena de conexión

Los clientes heredados de Event Hubs le permiten agregar componentes al cadena de conexión recuperado desde el portal de Azure. 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 cadenas de conexión en el formulario publicado por Azure Portal.

Agregar "TransportType=AmqpWebSockets"

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

Agregar "Authentication=Managed Identity"

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

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

Habilitación y configuración del registro para Event Hubs

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

Además de habilitar el registro, establecer el nivel de registro en VERBOSE o DEBUG proporciona información sobre el estado de la biblioteca. En las secciones siguientes se muestran ejemplos de configuraciones de log4j2 y logback para mitigar el exceso de mensajes cuando se habilita el registro detallado.

Configuración de Log4J 2

Siga estos pasos para configurar Log4J 2:

  1. Agregue las dependencias en el pom.xml mediante 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 al pom.xml con las del ejemplo de registro pom.xml, en la sección "Dependencias obligatorias para logback".
  2. Agregue logback.xml a la carpeta src/main/resources.

Habilitación del registro de transporte de AMQP

Si habilitar el registro de eventos del cliente no es suficiente para diagnosticar los problemas, puede habilitar el registro de eventos 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 implementación de java.util.logging.Handler. Para ver 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 entorno PN_TRACE_FRM=1.

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 de registros

Una forma de reducir los registros es cambiar el nivel de detalle. Otra manera consiste en agregar filtros que excluyan los registros de los paquetes de nombres del registrador como com.azure.messaging.eventhubs o com.azure.core.amqp. Para obtener ejemplos, consulte los archivos XML de las secciones Configurar Log4J 2 y Configurar logback.

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 mensaje onDelivery 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 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