Skip to content

Commit a614486

Browse files
michaelklishinmichaelklishin
committed
New doc guide on user-configurable limits and timeouts
Closes #2328.
1 parent 321a942 commit a614486

File tree

14 files changed

+267
-58
lines changed

14 files changed

+267
-58
lines changed

‎docs/limits.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: Configurable Limits
3+
---
4+
5+
# Configurable Limits and Timeouts
6+
7+
## Introduction
8+
9+
This guide provides an overview of the configurable limits and timeouts provided by RabbitMQ.
10+
11+
This guide intentionally leaves out some advanced limits as well as limits that cannot be configured via `rabbitmq.conf`,
12+
virtual host [metadata](./vhosts#limits), [policies](./policies), or other configuration means,
13+
but are instead controlled programmatically (for example, by RabbitMQ core or plugins).
14+
15+
:::note
16+
17+
In this guide, we define a configurable limit as a setting, configured via `rabbitmq.conf`, virtual host [metadata](./vhosts#limits),
18+
a [policy](./policies), an [operator policy](./policies#operator-policies), or any other means, that controls how many connections, channels, queues, streams,
19+
or other application-controlled resources would be allowed in a cluster or on a specific node.
20+
21+
Many of these limits are covered in more detail in dedicated guides.
22+
23+
:::
24+
25+
26+
## Why Use Configurable Limits {#why}
27+
28+
Modern messaging and streaming protocols, such as those supported by RabbitMQ, give application
29+
developers the freedom to define their topology resources (such as queues and streams, exchanges, bindings
30+
and so on).
31+
32+
Some of these resources can be unintentionally leaked by applications. For example, an application
33+
can leave a connection (or channel, session) open, not clean up queues or streams that are
34+
no longer needed, and so on.
35+
36+
Configurable limits are a protection mechanism that allows cluster operators to prevent such
37+
applications from using enough resources to affect other applications or cluster stability.
38+
39+
Such guardrails are particularly important when RabbitMQ clusters are offered as a service.
40+
41+
42+
## Available Limits
43+
44+
### Per Virtual Host Limits {#per-virtual-host}
45+
46+
[Per virtual host limits](./vhosts#limits), as the name suggests, apply to a specific
47+
virtual host:
48+
49+
* The maximum number of concurrent client connections in the virtual host
50+
* The maximum number of queues and streams that can be declared in a virtual host
51+
52+
### Per User Limits {#per-user}
53+
54+
[Per user limits](./user-limits) apply to user accounts (usernames):
55+
56+
* The maximum number of concurrent client connections that authenticate as that user
57+
* The maximum number of concurrent channels open across all of the user's connections
58+
59+
### Per Connection Limits {#per-connection}
60+
61+
Per connection limits apply to individual client connections.
62+
63+
| [`rabbitmq.conf` Setting](./configure) | Type | Description | Default |
64+
|---------|------|-------------|---------|
65+
| `channel_max` | integer | Maximum number of AMQP 0-9-1 channels a client can open on a single connection. Protects against applications [leaking channels](./channels#monitoring). Channel number 0 is reserved for internal use. While the default is 2047, values between 16 and 128 are recommended for most use cases. | 2047 |
66+
| `session_max_per_connection` | integer | Maximum number of AMQP 1.0 sessions per connection | 1 |
67+
| `link_max_per_session` | integer | Maximum number of AMQP 1.0 links per session | 10 |
68+
| `handshake_timeout` | integer (milliseconds) | Maximum time allowed for AMQP 0-9-1 and AMQP 1.0 handshake to complete | 10000 (10 seconds) |
69+
| `ssl_handshake_timeout` | integer (milliseconds) | Maximum time allowed for TLS handshake to complete | 5000 (5 seconds) |
70+
| `heartbeat` | integer (seconds) | [Heartbeat timeout](./heartbeats) value suggested by the server during connection negotiation | 60 |
71+
| `frame_max` | integer (bytes) | Maximum AMQP 1.0, AMQP 0-9-1 and [RabbitMQ Stream Protocol](./stream) frame size. **Should not be changed**; rely on server and client library defaults. | 131072 (128 KiB) |
72+
| `initial_frame_max` | integer (bytes) | Maximum frame size before connection tuning. **Should not be changed**; rely on server and client library defaults. | 4096 |
73+
74+
### Per Channel Limits {#per-channel}
75+
76+
`consumer_max_per_channel` controls the maximum number of consumers that can be registered on a single channel.
77+
This setting protects against applications leaking consumers.
78+
79+
The default is unlimited. To set a limit, configure it in `rabbitmq.conf`:
80+
81+
```ini
82+
consumer_max_per_channel = 10
83+
```
84+
85+
### Per Cluster Limits {#per-cluster}
86+
87+
The following settings are defined in `rabbitmq.conf` but effectively
88+
apply to the entire cluster, because the entities they limit are replicated across all nodes.
89+
90+
| [`rabbitmq.conf` Setting](./configure) | Type | Description | Default |
91+
|---------|------|-------------|---------|
92+
| `vhost_max` | integer | Maximum number of virtual hosts that can be created in the cluster | unlimited |
93+
| `cluster_exchange_limit` | integer | Maximum number of exchanges that can be declared in the cluster | unlimited |
94+
| `cluster_queue_limit` | integer | Maximum number of queues that can be declared in the cluster | unlimited |
95+
96+
:::warning
97+
98+
As these settings are cluster-wide but configured individually for each node using its `rabbitmq.conf` configuration file,
99+
they must be set to the same value across all cluster nodes.
100+
101+
:::
102+
103+
### Per Node Limits {#per-node}
104+
105+
Per node limits apply to individual cluster nodes. They affect all virtual hosts and users.
106+
107+
Due to their coarse-grained nature, these limits are typically used as guardrails in
108+
environments where RabbitMQ clusters are offered as a service and cluster operators have no
109+
understanding or control over what the deployed applications do.
110+
111+
See also: [open file handles limit](./networking#open-file-handles-limit).
112+
113+
| [`rabbitmq.conf` Setting](./configure) | Type | Description | Default |
114+
|---------|------|-------------|---------|
115+
| `consumer_timeout` | positive integer (milliseconds) | Defines [how long RabbitMQ will wait for delivery acknowledgements](./consumers#acknowledgement-timeout) from consumers | 1800000 (30 minutes) |
116+
| `connection_max` | integer | Maximum number of concurrent client connections a node will accept | unlimited |
117+
| `channel_max_per_node` | integer | Maximum number of channels across all connections on a node | unlimited |
118+
| `ranch_connection_max` | integer | Maximum number of concurrent TCP connections a node will accept; includes [HTTP API](./http-api-reference) connections | unlimited |
119+
| `max_message_size` | integer (bytes) | Maximum message size that messaging and streaming clients can publish. Messages larger than this will be rejected. Maximum allowed value is 512 MiB. | 134217728 (128 MiB) |
120+
| `management.http.max_body_size` | integer (bytes) | Maximum HTTP API request body size | 20971520 (20 MiB) |
121+
122+
### Per Queue Limits {#per-queue}
123+
124+
Individual queues can have limits configured via [policies](./policies):
125+
126+
* [Queue length limit](./maxlength): limits the maximum number of ready messages or total message bytes in a queue.
127+
When the limit is reached, messages are either dropped from the head or new publishes are rejected.
128+
* [Message TTL](./ttl#per-queue-message-ttl): messages in a queue expire after a specified time period.
129+
* [Queue TTL](./ttl#queue-ttl): queues are automatically deleted after a period of inactivity.
130+
* **Delivery limit** ([quorum queues](./quorum-queues#poison-message-handling)): maximum number of delivery attempts before a message is dropped or dead-lettered.
131+
Default is 20 in RabbitMQ 4.0+, was unlimited in 3.x. Configured via the `delivery-limit` policy key or queue argument.
132+
* **Priority levels** ([priority queues](./priority)): `x-max-priority` queue argument defines the maximum priority level (1-255).
133+
Values between 1 and 5 are recommended for optimal performance.
134+
135+
### Per Stream Limits {#per-stream}
136+
137+
Streams have [retention settings](./streams#retention) that control data expiration:
138+
139+
* `max-age`: maximum age of messages in the stream (e.g., `7D` for 7 days)
140+
* `max-length-bytes`: maximum total size of the stream in bytes
141+
142+
When retention limits are reached, the oldest segments are discarded. These can be configured via
143+
[policies](./policies) or as [optional stream arguments](./streams#declaring) at stream declaration time.
144+
145+
Consult the [streams guide](./streams) to learn more.
146+
147+
### Protocol-Specific Limits {#protocol-specific}
148+
149+
Some protocols supported by RabbitMQ have their own specific limits.
150+
151+
#### MQTT {#mqtt}
152+
153+
[MQTT](./mqtt) connections have a session expiry interval limit:
154+
155+
| [`rabbitmq.conf` Setting](./configure) | Type | Description | Default |
156+
|---------|------|-------------|---------|
157+
| `mqtt.max_session_expiry_interval_seconds` | integer (seconds) | Maximum [session expiry interval](./mqtt#session-expiry) that MQTT clients can request | 86400 (1 day) |

‎docs/maxlength/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ define it using a [policy](./policies) (this option is highly recommended)
3333
or by clients using the [queue's optional arguments](./queues#optional-arguments).
3434
In a scenario where the maximum length is defined using both ways, that is, using a policy and using the arguments, then the minimum of the two values specified is used.
3535

36-
Queue length settings configured using [operator policies](./policies#operator-policies).
36+
Queue length settings can also be configured using [operator policies](./policies#operator-policies).
3737

3838
In all cases, the number of messages in the **ready** state are used. [Messages unacknowledged by consumers](./confirms)
3939
do not count towards the limit.

‎docs/user-limits.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The limits can be configured using CLI tools or the [HTTP API](./management#http
3737

3838
## Maximum Number of Connections {#connections}
3939

40-
To limit how many connection a user can open, set the `max-connections` limit to
40+
To limit how many connections a user can open, set the `max-connections` limit to
4141
a positive integer:
4242

4343
<Tabs groupId="examples">
@@ -138,7 +138,7 @@ EOF
138138
</Tabs>
139139

140140
The limit is applied to the total number of channels across all connections opened
141-
by the user. Therefore, it must be equal or greater than that the aforementioned maximum
141+
by the user. Therefore, it must be equal to or greater than the aforementioned maximum
142142
connection limit.
143143

144144
## Listing User Limits {#listing}

0 commit comments

Comments
 (0)