Merge pull request #3144 from emqx/clent-tag-ratelimit

feat: clent tag ratelimit

Author: Meggielqk

directory_ee.json

@@ -275,6 +275,10 @@
         {
           "title": "用户名配额限制",
           "path": "modules/username_quota"
+        },
+        {
+          "title": "客户端标签管理",
+          "path": "modules/client_tag"
         }
       ]
     },
@@ -1517,4 +1521,4 @@
       ]
     }
   ]
-}
+}

en_US/advanced/rate-limit.md

@@ -1,52 +1,56 @@
-# Rate limit
+# Rate Limit
 EMQX Broker specifies the limit on access speed and message speed. When the client's connection request speed exceeds the specified limit, the establishment of a new connection is suspended; when the message reception speed exceeds the specified limit, the reception of messages is suspended.
 
 Rate limit is a *backpressure* scheme that avoids system overload from the entrance and guarantees system stability and predictable throughput. The rate limit can be configured in `etc/emqx.conf` :
 
-| Configuration item                  | Type            | Default value | Description                                                  |
-| ----------------------------------- | --------------- | ------------- | ------------------------------------------------------------ |
-| listener.tcp.external.max_conn_rate | Number          | 1000          | The maximum allowable connection rate on this node (conn/s)  |
-| zone.external.rate_limit.conn_messages_in         | Number,Duration | No limit      | Maximum allowable publish rate on a single connection (msg/s) |
-| zone.external.rate_limit.conn_bytes_in    | Size,Duration   | No limit      | Maximum allowable packet rate on a single connection (bytes/s) |
+| Configuration Item                        | Type             | Default Value | Description                                                  |
+| ----------------------------------------- | ---------------- | ------------- | ------------------------------------------------------------ |
+| listener.tcp.external.max_conn_rate       | Number           | 1000          | The maximum allowable connection rate on this node (conn/s)  |
+| zone.external.rate_limit.conn_messages_in | Number, Duration | No limit      | Maximum allowable publish rate on a single connection (msg/s) |
+| zone.external.rate_limit.conn_bytes_in    | Size, Duration   | No limit      | Maximum allowable packet rate on a single connection (bytes/s) |
 
-- **max_conn_rate** is the rate limit for connection establishment on a single emqx node. `1000` means that 1000 clients can access at most.
+- **max_conn_rate** is the rate limit for connection establishment on a single EMQX node. `1000` means that 1000 clients can access at most.
 - **conn_messages_in** is the rate limit for receiving PUBLISH packets on a single connection. `100,10s` means that the maximum PUBLISH message rate allowed on each connection is 100 every 10 seconds.
 - **conn_bytes_in** is the rate limit for receiving TCP packets on a single connection. `100KB,10s` means that the maximum TCP packet rate allowed on each connection is 100KB every 10 seconds.
 
 `conn_messages_in` and `conn_bytes_in` both provide limits for a single connection. EMQX Broker currently does not provide a global message rate limit.
 
-## Rate limit explanation 
+## Rate Limit Explanation 
 EMQX Broker uses the [Token Bucket](https://en.wikipedia.org/wiki/Token_bucket) algorithm to control all Rate Limits. The logic of the token bucket algorithm is as follows:
 
 ![image-20190604103907875](../assets/token-bucket.jpg)
 
-- There is a bucket that can hold the maximum burst of the token. The maximum burst is abbreviated as b.
-- There is a rate for adding tokens to the bucket per second, abbreviated as r. When the bucket is full, no tokens are added to the bucket.
-- Whenever 1 (or N) request arrives, take 1 (or N) token from the bucket. If the token is not enough, it will be blocked and wait for the token to be generated.
+- A *bucket* holds tokens, with a maximum capacity of $burst$ tokens, abbreviated as $b$.
+- Tokens are added to the bucket at a constant rate $rate$, abbreviated as $r$. When the bucket is full, no additional tokens are added.
+- When a request (or N requests) arrives, it must consume 1 (or N) tokens from the bucket. If there are not enough tokens, the request is blocked until more tokens are generated.
 
-It can be seen from this algorithm:
+In this algorithm:
 
-- In the long run, the average value of the limited request rate is equal to the value of rate.
+1. When a large number of requests arrive and the bucket is full:
 
-- When the actual request reaching speed is M, and M> r, then the maximum (peak) rate that can be achieved in actual operation is M = b + r.
+   The maximum number of tokens that can be consumed per unit time is $b + r/1$, i.e., all the tokens in the bucket plus those generated during the unit time.
 
-It is easy to think that the maximum rate M is the speed that can consume the full state token bucket in 1 unit of time. The consumption rate of token bucket is M-r, so we can see that: b / (M-r) = 1, and we get M = b + r
-  
-  
+   This is the maximum achievable rate: $M = b + r/1$.
 
-### Application of Token Bucket Algorithm in EMQX Broker
+2. After all tokens in the bucket are consumed (i.e., the bucket is empty):
+
+   The number of tokens available per unit time is $0 + r/1$, meaning only newly generated tokens can be consumed.
+
+   This represents the long-term average rate: $r$.
+
+### Application of Token Bucket Algorithm in EMQX
 When the following configuration is used for packet rate limiting:
 
 ```
 zone.external.rate_limit.conn_bytes_in = 100KB,10s
 ```
 
-EMQX Broker will initialize the rate-limit processor of each connection with two values:
+EMQX will initialize the rate-limit processor of each connection with two values:
 
 - rate = 100 KB / 10s = 10240 B/s
 - burst = 100 KB = 102400 B
 
-According to the algorithm in [Message Rate Limitation Explanation](#rate-limit-explanation), it is known:
+According to the algorithm in [Rate Limit Explanation](#rate-limit-explanation), it is known:
 
 - In the long run, the allowable average rate is limited to 10240 B/s
 - The allowable peak rate is 102400 + 10240 = 112640 B/s

en_US/modules/client_tag.md

@@ -0,0 +1,122 @@
+# Client Tags and Group-Based Rate Limiting
+
+Starting from EMQX version 4.4.33, EMQX introduces a client tagging feature. This feature allows you to assign tags to clients based on business logic and apply differentiated rate-limiting policies to clients under different tags.
+
+This module relies heavily on [HTTP Authentication/ACL](./http_authentication.md), using the data returned from the authentication interface to assign tags to clients. This document details the working mechanism, configuration, and management of client tags.
+
+## How It Works
+
+The core principle of client tagging is “group first, then rate limit.” EMQX automatically assigns clients to different groups based on the `tag` returned by the HTTP authentication service, and then applies independent rate-limiting policies to each group.
+
+The full workflow is as follows:
+
+1. **Create Tags**: Tags are pre-created in the EMQX Dashboard, each with its own rate-limiting strategy. A built-in `default` tag exists and cannot be deleted. It is used for clients that do not match any tag.
+2. **Client Connection**: A client initiates a connection request.
+3. **HTTP Authentication**: EMQX sends client information to the external HTTP authentication service.
+4. **Tag Assignment**: The authentication service includes tag information in its response based on custom business logic.
+5. **Apply Policy**: EMQX parses the tag from the response, associates the client with the corresponding tag, and enforces the rate-limiting policy configured for that tag.
+
+### Tag Assignment Logic
+
+- If HTTP authentication is successful (status code `200`) and the `client_attrs.tag` in the response matches a pre-created tag, the client is assigned to that tag.
+- If the `tag` field is missing or the value does not match any existing tag, the client is automatically assigned to the `default` tag.
+- If HTTP authentication fails (non-`200` status code), the client connection is denied, and no tag is assigned.
+
+::: tip Note
+
+You must create tags in the Dashboard first; only then will tags returned by the HTTP service take effect. The rate-limiting policy for the `default` tag can also be customized to control default client behavior.
+
+If the HTTP Authentication module is not enabled, all clients are automatically assigned to the `default` tag.
+
+:::
+
+## HTTP Authentication Interface Specification
+
+To enable EMQX to recognize client tags, your HTTP authentication service must comply with the following interface specification.
+
+When authentication is successful, the HTTP service should return a 200 status code and a response body containing a JSON object. The `client_attrs.tag` field in the object specifies the client’s tag.
+
+**Example Response Body:**
+
+```json
+{
+  "result": "allow",
+  "client_attrs": {
+    "tag": "group_a"
+  }
+}
+```
+
+**Field Descriptions:**
+
+- `result`: `string` type. Currently reserved for EMQX 5.0 compatibility and does not affect authentication results. EMQX determines authentication success based solely on HTTP status code.
+- `client_attrs`: `object` type. Stores additional client attributes.
+  - `tag`: `string` type. Specifies the client’s tag name. EMQX uses this value to group the client.
+
+## Rate Limiting Policies and Handling
+
+EMQX provides fine-grained rate-limiting strategies per tag, allowing you to control resource usage per client group.
+
+### Configurable Limits
+
+| Limit Type                        | Unit         | Description                                                  |
+| --------------------------------- | ------------ | ------------------------------------------------------------ |
+| Sent Message TPS Limit            | Messages/sec | Limits the number of messages a client can publish per second (TPS). |
+| Subscribe Message TPS Limit       | Messages/sec | Limits the number of messages EMQX can deliver to a client per second. |
+| Sent Traffic Limit (bytes/s)      | Bytes/sec    | Limits the message traffic a client can publish per second.  |
+| Subscribe Traffic Limit (bytes/s) | Bytes/sec    | Limits the message traffic a client can deliver per second.  |
+| Maximum QoS Level                 | 0, 1, 2      | Limits the maximum QoS level a client is allowed to publish with. |
+
+::: tip
+
+If a limit value is empty or set to `0`, that limit is **not applied**.
+
+:::
+
+### Enforcement Mechanism
+
+When a client exceeds the rate limits configured for its assigned tag, EMQX handles it differently based on the type of limit:
+
+- **For publishing clients**:
+  - **QoS Limit**: If a client tries to publish with a QoS level higher than allowed, the message is dropped.
+  - **Rate/Byte Limit**: If the client exceeds the message or byte rate limit, EMQX applies backpressure, temporarily blocking data reads from the client’s socket to slow down publishing. This behaves similarly to [EMQX’s built-in rate limiting](../advanced/rate-limit.md) but does not disconnect the client.
+- **For subscribing clients**:
+  - **Rate/Byte Limit**: If the message delivery rate exceeds the configured limit, subsequent messages are dropped to prevent the client from being overwhelmed.
+
+::: tip Note
+
+For performance reasons, EMQX does not enqueue messages that exceed rate limits. They are dropped immediately.
+See: [Inflight Window and Message Queue](../advanced/inflight-window-and-message-queue.md).
+
+Due to batch processing of message delivery, if the delivery rate or byte limit is set too low, rate limiting may be triggered frequently, causing the actual delivery rate to fall below the configured limit.
+
+:::
+
+## Manage Client Tags via Dashboard
+
+You can manage client tags and their rate-limiting policies conveniently through the EMQX Dashboard.
+
+1. Open the EMQX Dashboard in your browser.
+2. In the left menu, click **Modules**.
+3. Click **Add Module** on the page, then select and add **Client Tag Management** from the list.
+4. Once added, a **Client Tag Management** module will appear in the module list. Click **Manage** to enter the Client Tag Management page.
+
+### Client Tags
+
+Under the **Client Tags** tab, all created tags are displayed in a list, including the built-in `default` tag. You can:
+
+- **View**: See tag names and the number of currently associated clients.
+- **Create**: Click **Add** to add new tags and configure rate-limiting policies. For detailed configuration descriptions, see [Configurable Limits](#configurable-limits).
+- **Manage**: Edit rate-limiting strategies or view the client list under a tag by clicking the **View Client List** button.
+- **Delete**: Delete a tag that is no longer needed. 
+
+### Client Search
+
+Under the **Client Search** tab, you can view all online clients assigned to different tags. The list supports pagination, and you can click a client ID to view detailed information for troubleshooting and monitoring. You can quickly locate clients or tags by client ID or tag name.
+
+## Monitoring and Logs
+
+To assist with monitoring and debugging group-based rate limiting, EMQX provides relevant metrics and logging support:
+
+- **Prometheus Metrics**: EMQX exposes metrics for messages dropped due to rate limiting, which can be integrated with monitoring and alerting systems.
+- **Logs**: When rate limiting is triggered, EMQX logs the event. The logging system supports **sampling** to avoid performance degradation during traffic spikes.

zh_CN/advanced/rate-limit.md

@@ -8,7 +8,7 @@ keywords: rate-limit
 # 描述
 description:
 # 分类
-category: 
+category:
 # 引用
 ref:
 ---
@@ -35,17 +35,23 @@ EMQX 使⽤[令牌桶 (Token Bucket)](https://en.wikipedia.org/wiki/Token_bucket
 
 ![image-20190604103907875](../assets/token-bucket.jpg)
 
-- 存在一个可容纳令牌(Token) 的最大值 burst 的桶(Bucket)，最大值 burst 简记为 b 。
-- 存在一个 rate 为每秒向桶添加令牌的速率，简记为 r 。当桶满时则不不再向桶中加⼊入令牌。
-- 每当有 1 个(或 N 个)请求抵达时，则从桶中拿出 1 个 (或 N 个) 令牌。如果令牌不不够则阻塞，等待令牌的⽣生成。
+- 存在一个可容纳令牌 (Token) 的桶 (Bucket) ，可容纳令牌数量的最大值为 $burst$ ，简记为 $b$ 。
+- 存在一个每秒向桶添加令牌的速率 $rate$，简记为 $r$ 。当桶满时则不再向桶中加入令牌。
+- 每当有 1 个 (或 N 个) 请求抵达时，则从桶中拿出 1 个 (或 N 个) 令牌。如果令牌不够则阻塞，等待令牌的生成。
 
-由此可知该算法中:
+该算法中:
 
-- 长期来看，所限制的请求速率的平均值等于 rate 的值。
+1. 在大量请求到达时，假设当前 Bucket 已满。
 
-- 记实际请求达到速度为 M，且 M > r，那么，实际运⾏中能达到的最大(峰值)速率为 M = b + r，证明：
+   那么单位时间内可被请求消耗的 Token 数量最多为 $b + r/1$ 。即桶中的所有 Token 和单位时间内生成的所有 Token。
 
-  容易想到，最大速率 M 为：能在1个单位时间内消耗完满状态令牌桶的速度。而桶中令牌的消耗速度为 M - r，故可知：b / (M - r) = 1，得 M = b + r
+   该速率即为实际能够达到的最大速率。记为 $M = b + r/1$。
+
+2. 在桶中 Token 被完全消耗后（Bucket 为空之后）
+
+   单位时间内可被请求消耗的 Token 数量最多为 $0 + r/1$。即该单位时间内生成的所有 Token。
+
+   该速率即为长期来看所能达到的平均速率 $r$
 
 ### 令牌桶算法在 EMQX 中的应用
 
@@ -60,7 +66,7 @@ EMQX 将使用两个值初始化每个连接的 rate-limit 处理器：
 - rate = 100 KB / 10s = 10240 B/s
 - burst = 100 KB = 102400 B
 
-根据 [消息速率限制原理](#rate-limit-explanation) 中的算法，可知：
+根据[消息速率限制原理](#速率限制原理)中的算法，可知：
 
 - 长期来看允许的平均速率限制为 10240 B/s
 - 允许的峰值速率为 102400 + 10240 = 112640 B/s