跳到主要内容

限流信息

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。
decisionallowed、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 配置。