On this page
consumer_timeout es el timeout de confirmación de entregas de RabbitMQ. Si un consumidor retiene una entrega sin confirmarla durante más tiempo que el timeout, RabbitMQ cierra el canal de ese consumidor con una excepción de canal PRECONDITION_FAILED y los mensajes sin confirmar vuelven a la cola para entregarse de nuevo. El valor predeterminado es de 30 minutos. A partir de RabbitMQ 4.3 solo aplica a las colas de quórum (quorum queues).
Solo afecta a los consumidores en modo de confirmación manual, la configuración habitual en los clientes AMQP 0-9-1 cuando no se pueden perder mensajes: el broker entrega un mensaje y espera a que el consumidor confirme los que ya terminó de procesar. El timeout existe para detectar consumidores que tomaron un mensaje y luego se colgaron, de modo que el trabajo vuelva a la cola en lugar de quedar retenido para siempre. Pero también atrapa a consumidores sanos cuyos trabajos simplemente tardan más de 30 minutos, y ahí empieza casi toda la confusión: la aplicación está en ejecución, la conexión está abierta y la cantidad de consumidores en la UI de administración bajó a cero sin hacer ruido.
Cómo se ve el error de timeout de consumidor
El broker registra el cierre del canal con el consumer tag, el canal, la cola y el delivery tag. El mensaje que muestra la documentación de RabbitMQ es como este:
Consumer 'consumer-tag-998754663370' on channel 1 and queue 'qq.1' in vhost '/' has timed out
waiting for a consumer acknowledgement of a delivery with delivery tag = 10. Timeout used: 180000 ms.Del lado del cliente llega como una excepción de canal con PRECONDITION_FAILED. Como cierra el canal y no la conexión, la biblioteca cliente a menudo sigue conectada y no registra nada evidente, salvo que se maneje el cierre del canal. La cola vuelve a mostrar sus mensajes como listos (ready), se entregan de nuevo con el flag redelivered activado y el trabajo lento puede ejecutarse dos veces.
Tres razones por las que un consumidor de RabbitMQ deja de consumir
El timeout es una de las tres formas en que un consumidor deja de consumir sin que la aplicación se lo pida. En la UI de administración las tres se ven igual, pero cada una requiere una solución distinta:
- El timeout de confirmación cerró el canal. Aparece la línea de log anterior, la conexión sigue activa y el consumidor desapareció. El trabajo tardó demasiado, o el consumidor se colgó.
- El broker canceló al consumidor. Cuando se elimina una cola, o falla el nodo que la aloja, RabbitMQ envía al cliente un
basic.cancelasíncrono. Los clientes anuncian la capacidadconsumer_cancel_notify, como hacen por defecto los clientes oficiales de RabbitMQ, y la biblioteca cliente la expone mediante un callback, por ejemplohandleCancelen el cliente de Java. Si la aplicación ignora ese callback, se queda con un canal sin ningún consumidor. - La conexión murió. Un balanceador de carga, un firewall o un gateway NAT descartó una conexión TCP inactiva, o el proceso cliente se congeló. Los heartbeats lo detectan: el valor predeterminado sugerido es de 60 segundos y, tras dos heartbeats perdidos, el otro extremo se considera inalcanzable. Los TCP keepalives pueden cumplir la misma función a nivel del sistema operativo.
El orden de revisión es primero el log del broker, después los callbacks de canal y de cancelación del cliente y, por último, la red. El log del broker le dice en pocos segundos cuál de las tres fue.
Configuración de consumer_timeout: global, por cola o desactivado
Defina el valor del timeout de forma global en el archivo de configuración de RabbitMQ, rabbitmq.conf, en milisegundos:
# one hour
consumer_timeout = 3600000Por cola, a partir de RabbitMQ 3.12, con una policy o un argumento de cola. La policy es la mejor herramienta, porque se puede cambiar sin volver a desplegar la aplicación:
rabbitmqctl set_policy queue_consumer_timeout "with_delivery_timeout\.*" '{"consumer-timeout":3600000}' --apply-to quorum_queuesEl argumento de cola es x-consumer-timeout, que se define al declarar la cola, también en milisegundos.
RabbitMQ evalúa el timeout una vez por minuto, así que no se admiten valores menores a un minuto y no se recomiendan valores menores a cinco minutos. Se puede desactivar en advanced.config definiendo consumer_timeout como undefined, pero la documentación recomienda un valor alto, de algunas horas, en lugar de apagarlo.
El cambio de RabbitMQ 4.3: solo colas de quórum
A partir de RabbitMQ 4.3, los timeouts de confirmación de entregas solo los admiten las colas de quórum. Esto tiene dos consecuencias:
- Los consumidores de colas clásicas pierden la protección. Un consumidor que toma un mensaje de una cola clásica y se cuelga lo retendrá hasta que se cierre el canal o la conexión. Si dependía del timeout para recuperar consumidores atascados en colas clásicas, ahora necesita timeouts del lado del cliente o monitoreo.
- Pasar a colas de quórum puede activarlo. Una carga de trabajo que funcionaba sin problemas en colas clásicas con trabajos de una hora puede empezar a ver cierres de canal con
PRECONDITION_FAILEDdespués de migrar a colas de quórum. Defina unconsumer-timeoutpor cola para esas colas como parte de la migración, no después del primer incidente.
Las diferencias generales entre tipos de cola se explican en cómo migrar de colas clásicas a colas de quórum.
Cómo detectar consumidores atascados antes de que expire el timeout
Un consumidor a punto de alcanzar el timeout parece sano desde afuera: conectado, suscrito y con mensajes en tránsito. Tres revisiones lo delatan a tiempo.
Mensajes sin confirmar que no avanzan. Compare los mensajes listos, los sin confirmar y la cantidad de consumidores por cola:
rabbitmqctl list_queues -p / name messages_ready messages_unacknowledged consumers consumer_utilisationUna cola cuyo messages_unacknowledged se mantiene plano mientras crece messages_ready tiene consumidores que retienen entregas que no están terminando. Un consumer_utilisation muy por debajo de 1.0 en una cola con backlog dice lo mismo desde el otro lado: la cola tiene mensajes pero no puede entregarlos, porque los consumidores llegaron a su límite de prefetch.
Qué consumidores los retienen. rabbitmqctl list_consumers lista cada suscripción con su canal, su consumer tag, si se esperan confirmaciones y su límite de prefetch. Un consumidor con un prefetch alto en una cola lenta es el primer sospechoso.
La cantidad de consumidores a lo largo del tiempo. En Prometheus, con las métricas por objeto habilitadas para que los valores se reporten por cola y no agregados, configure alertas cuando rabbitmq_queue_consumers baje a cero en colas que siempre deberían tener consumidores, y cuando rabbitmq_queue_messages_unacked suba sin un aumento equivalente en las tasas de entrega y confirmación. Esas dos alertas detectan el timeout, una cancelación iniciada por el broker y una conexión muerta, lo que ocurra primero.
Cómo evitar que los consumidores excedan el timeout
Subir el timeout es la solución correcta solo cuando el trabajo realmente tarda eso. Lo demás depende del comportamiento del cliente:
- Dimensione el timeout por cola. Defina
consumer-timeouten las colas que llevan trabajos largos, con un margen por encima del mayor tiempo de procesamiento legítimo, y deje intacto el valor global predeterminado. - Mantenga bajo el prefetch para trabajo lento. Cada mensaje precargado ya es una entrega que el timeout está contando. Con un prefetch de 50 y trabajos que tardan un minuto cada uno, la entrega número 31 lleva más de 30 minutos retenida antes de que el consumidor siquiera la empiece, y el canal se cierra con el timeout predeterminado. Consulte prefetch count en RabbitMQ.
- Confirme en el mismo canal que recibió la entrega, y en todas las rutas del código, incluida la de excepciones. Un ack faltante en una rama de error es la causa más común de un consumidor que retiene entregas hasta exceder el timeout.
- Maneje el cierre de canal y las notificaciones de cancelación. Ante un cierre de canal o un
basic.cancel, abra un canal nuevo y vuelva a suscribirse. La recuperación automática de conexiones de las bibliotecas cliente reconecta las conexiones caídas, pero no siempre cubre un canal cerrado aislado ni una cancelación iniciada por el broker. - Haga que el procesamiento sea idempotente. Una entrega que excedió el timeout vuelve a la cola y se entrega de nuevo, así que un trabajo que estaba al 90 % se ejecuta otra vez. Los mensajes que nunca podrán terminar a tiempo deben ir a una dead letter queue y no a un ciclo de reentregas; consulte dead letter queues en RabbitMQ.
- Configure alertas sobre mensajes sin confirmar y cantidad de consumidores por cola, no solo sobre la profundidad de la cola. Cero consumidores en una cola que siempre debería tenerlos es la señal más temprana de los tres modos de falla.
Estos patrones aparecen con frecuencia en los tickets de soporte de RabbitMQ que atendemos: consumidores reportados como desaparecidos mientras la aplicación está sana, después de una migración a colas de quórum o de un cambio en los límites de memoria. Si necesita una segunda opinión sobre un clúster que se comporta así, el soporte de RabbitMQ de AceMQ lo cubre, y la guía de resolución de problemas de RabbitMQ recorre el diagnóstico completo.
Fuentes
Preguntas frecuentes
¿Qué es consumer_timeout en RabbitMQ?
Es el timeout de confirmación de entregas. Si un consumidor retiene una entrega sin confirmarla durante más tiempo que el timeout, RabbitMQ cierra el canal de ese consumidor con una excepción de canal PRECONDITION_FAILED y los mensajes sin confirmar vuelven a la cola. El valor predeterminado es de 30 minutos.
¿Cuál es el timeout de consumidor predeterminado en RabbitMQ?
30 minutos (1,800,000 ms). RabbitMQ revisa una vez por minuto si debe aplicarlo, por lo que no se admiten valores menores a un minuto y no se recomiendan valores menores a cinco minutos.
¿Cómo cambio el timeout de consumidor para una sola cola?
A partir de RabbitMQ 3.12, defina la clave consumer-timeout en una policy, o el argumento x-consumer-timeout al declarar la cola. Ambos se expresan en milisegundos. Un valor por cola es más seguro que subir el consumer_timeout global para todas las colas del clúster.
¿consumer_timeout aplica a las colas clásicas en RabbitMQ 4.3?
No. A partir de RabbitMQ 4.3, los timeouts de confirmación de entregas solo los admiten las colas de quórum (quorum queues). En 4.3, el broker ya no cierra a un consumidor de una cola clásica que retiene una entrega indefinidamente.
¿Se puede desactivar el timeout de consumidor en RabbitMQ?
Sí, definiendo consumer_timeout como undefined en advanced.config, aunque la documentación de RabbitMQ lo desaconseja. Un valor alto, por ejemplo de algunas horas, mantiene la protección sin matar los trabajos largos.
¿Por qué la cantidad de consumidores de RabbitMQ baja a cero mientras la aplicación sigue en ejecución?
Normalmente por una de tres causas: el timeout de confirmación de entregas cerró el canal del consumidor, el broker canceló al consumidor porque su cola se eliminó o dejó de estar disponible, o la conexión TCP murió y se descartó tras no recibir los heartbeats. Los clientes que no vuelven a abrir el canal ni a suscribirse siguen conectados, pero no consumen nada.
Guías, comparativas e investigación

