Server config comment says "heartbeat interval", docs say "heartbeat timeout"

[adamhooper]

The heartbeat documentation does not agree with server-config comments..

According to the docs (emphasis mine):

It is important to not confuse the timeout value with the interval one. RabbitMQ configuration exposes the timeout value, so do the officially supported client libraries. However some clients might expose the interval, potentially causing confusion.

Reading this, I paraphrase: "okay, the server and these docs are aligned on 'heartbeat timeout', and I should ignore clients' docs because they might be wrong."

And indeed, as the docs warn, clients are confusing. For instance, Pika docs (emphasis mine):

Starting with RabbitMQ 3.5.5, the broker’s default heartbeat timeout decreased from 580 seconds to 60 seconds.

But.... from deps/rabbit/docs/rabbitmq.conf.example:

## Set the default AMQP 0-9-1 heartbeat interval (in seconds).
## Related doc guides:
##
## * https://rabbitmq.com/heartbeats.html
## * https://rabbitmq.com/networking.html
##
# heartbeat = 60

Reading this, I paraphrase: "This is the very opposite of what the docs say. Indeed, the docs warn me to watch out for code like this because it's confusing."

Indeed, it isn't a heartbeat interval: with heartbeat = 60, RabbitMQ sends a heartbeat frame every 30s. (I tested.)

[michaelklishin]

I will convert this issue to a GitHub discussion. Currently GitHub will automatically close and lock the issue even though your question will be transferred and responded to elsewhere. This is to let you know that we do not intend to ignore this but this is how the current GitHub conversion mechanism makes it seem for the users :(

[michaelklishin]

Your observations are mostly on point. However, this is a lot more involved than it seems. First of all, this is a timeout. The AMQP 0-9-1 spec says that it should represent two or more missed communications (heartbeats). This is how RabbitMQ server and official clients (Java, .NET) work today:

• The value is treated as a timeout
• Heartbeat sender timer uses roughly half of that value
• Two missed heartbeats trigger a peer unavailability event

However, as you have found, certain community projects have interpreted this differently and use it as an interval. Some of them a good decade old so changing this across 20+ clients in our ecosystem is not something that can be done easily.

If you have suggestions for what the rabbitmq.conf.example should say, please submit a PR (note that v3.8.x is the branch we link to in most places). The doc guide is also open source and contributions will be considered.

[michaelklishin]

@adamhooper I went ahead and edited rabbitmq.conf.example. I hope this revision is reasonably specific. If not, you are welcome to offer suggestions in PRs :) Thank you for bringing this up.

[adamhooper]

So quick and clear! Thank you -- the next readers won't be as perplexed.

…

On Fri., Feb. 26, 2021, 12:13 p.m. Michael Klishin, < ***@***.***> wrote: @adamhooper <https://github.com/adamhooper> I went ahead and edited rabbitmq.conf.example. I hope this revision <https://github.com/rabbitmq/rabbitmq-server/blob/v3.8.x/deps/rabbit/docs/rabbitmq.conf.example#L304-L317> is reasonably specific. If not, you are welcome to offer suggestions in PRs :) Thank you for bringing this up. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2852 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAACUPFCKMFI3IHQUZ5AV5LTA7JE5ANCNFSM4YIZBOFQ> .