限流信息
limit-count 插件会将每次评估记录在 $rate_limiting_info 变量中。其他受支持的限流插件 也可以填充该变量。在受支持的限流插件运行之前,其值为空字符串。
扩展的窗口诊断信息自 APISIX 3.20.0 和 API7 Enterprise 3.10.8 起提供。更早的版本只提供计数器 Key、配额、剩余配额和重置时间。
使用该变量
将 $rate_limiting_info 添加到访问日志格式或日志插件的 log_format 中,以记录评估结果。
字段没有固定的输出顺序。将该值解析为 JSON,并按字段名读取。默认的 NGINX 日志转义会将双引号表示为 \x22,因此在解析之前应先解码日志字段。日志插件可能使用自己的 JSON 转义方式。
示例
本地固定窗口请求产生的解码值类似于:
{
"rate_limiting_key": "/apisix/routes/limit-route:1:example.com",
"rate_limiting_limit": 100,
"rate_limiting_remaining": 99,
"rate_limiting_reset": 14,
"window_type": "fixed",
"window_size_ms": 60000,
"decision": "allowed",
"cost": 1,
"evaluated_at_ms": 1759212345678,
"current_window": {
"start_ms": 1759212300123,
"end_ms": 1759212360123,
"count": 1,
"created": true
}
}
字段
| 字段 | 说明 |
|---|---|
rate_limiting_key | 实际使用的计数器 Key。应将其视为实现中的值,而不是格式稳定、可按段解析的值。 |
rate_limiting_limit、rate_limiting_remaining | 应用的配额以及请求处理后剩余的配额。 |
rate_limiting_reset | 距离计数器重置还有多少秒。对于被拒绝的滑动窗口请求,这一时间可能早于当前窗口的结束时间。 |
window_type、window_size_ms | 窗口算法(fixed 或 sliding)以及以毫秒为单位的已配置 time_window。 |
decision | allowed、rejected 或 error。错误结果保留四个 rate_limiting_* 字段、window_type 和 window_size_ms,并省略其余字段。 |
cost | 该请求增加的计数值。 |
evaluated_at_ms | 网关时钟记录的评估时间,以毫秒为单位的 Unix 时间戳表示。 |
current_window.start_ms、current_window.end_ms | 当前窗口的边界,以毫秒为单位的 Unix 时间戳表示。 |
current_window.count | 计入该请求消耗量后的计数。本地固定窗口拒绝请求时,其值为 null。 |
current_window.created | 仅适用于固定窗口。对于创建本地窗口的请求,其值为 true;对于 Redis 策略,其值为 null。 |
current_window.id | 仅适用于滑动窗口。与时钟对齐的窗口标识。 |
previous_window.count、previous_window.weight、previous_window.weighted_count | 仅适用于滑动窗口。分别表示上一个窗口的计数、仍处 于滑动范围内的部分,以及加权计数。 |
不适用于当前窗口类型或配置的字段会被省略。适用但值未知的字段为 null。
窗口行为
固定窗口从某个 Key 的第一个被计数请求开始。对于 Redis 策略,窗口边界根据计数器的 TTL 确定。滑动窗口与时钟对齐,并结合当前计数和加权后的上一窗口计数。
cost 字段表示该请求增加的计数值。固定窗口会计入被拒绝的请求。滑动窗口和延迟同步只计入允许的请求,因此被拒绝请求的 cost 为 0。
延迟同步
当 Redis 策略使用 sync_interval 时,结果包含用于评估请求的快照:
| 字段 | 说明 |
|---|---|
delayed_sync.synced_at_ms | 网关实例上次读取 Redis 计数器的时间。 |
delayed_sync.synced_count | 当时 Redis 中的计数。 |
delayed_sync.local_delta | 此次请求之前尚未同步的本地增量。 |
current_window.count 是根据上次 Redis 快照及本地增量估算的值,不包含其他网关实例尚未同步的增量。
每次同步都会替换快照,过期快照会在其窗口结束时刷新。因此,窗口边界之后、下次同步之前的请求,其 evaluated_at_ms 可能晚于 current_window.end_ms。
多条规则
当 rules 包含多条规则时,该变量描述拒绝请求的规则;如果没有规则拒绝请求,则描述最后一条被评估的规则。
有关控制窗口算法、配额和同步策略的插件字段,请参阅 Limit Count 配置。