Compartir a través de

Solución de problemas de Azure Event Hubs

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 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 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 obtener más información, consulte Errores de AMQP en Azure Service Bus.

Problemas de permisos

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.

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 deberían preferir tratar a los clientes de Event Hubs como si fueran un único objeto, creando y utilizando una sola instancia durante toda la vida de la 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 a close() cuando haya terminado de usar un cliente.

Para usar la misma conexión AMQP al crear varios clientes, puede utilizar la marca EventHubClientBuilder.shareConnection(), mantener una referencia a ese EventHubClientBuilder y crear nuevos clientes a partir de esa misma instancia de constructor.

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 permitían a los clientes agregar componentes a la cadena de conexión recuperada desde 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 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 biblioteca de Azure.Identity, consulte nuestra entrada del blog Autenticación y el SDK de Azure.

Habilitación y configuración del registro

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 generados capturan el flujo de una aplicación antes de alcanzar el estado 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 su pom.xml usando 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 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.