> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 监控消费堆积

> 了解 AutoMQ 消费堆积指标的含义、计算口径和使用场景。

## 消费堆积是什么

当 Consumer Group 的消费进度落后于 Topic 的写入进度时，就会出现消费堆积。只看落后的 offset 数量，难以判断业务数据究竟晚了多久：相同的 offset 差值，在不同写入速率下可能对应不同的时间延迟。

对于使用 Kafka classic group protocol 的 Consumer Group，AutoMQ BYOC 数据面（5.5.0 及以上）提供 offset 距离和估算时间延迟两个指标。

## 消费堆积指标与维度

两个指标都以 `group`、`topic`、`partition` 标识一条时间序列，表示某个 Consumer Group 在某个 Topic Partition 上的消费进度。

| 指标 | 含义与计算口径 | 单位 |
| - | - | - |
| `consumer_offset_lag_count` | Partition 的 Log End Offset（LEO）减去 Consumer Group 已提交的 offset；结果小于 `0` 时记为 `0`。 | offset |
| `consumer_estimated_time_lag_milliseconds` | 根据已提交 offset 对应的估算 timestamp，计算该 Partition 的估算时间延迟。 | 毫秒 |

![上方 offset 位置轴显示单个 Partition 的 Offset Lag 为 30；下方时间轴显示 LogAppendTime 下估算时间延迟约为 5 分钟](https://mintcdn.com/automq/vquUtcTAr7VDdwPB/zh/automq-cloud/monitoring-alert/monitor-consumer-lag/consumer-lag-metrics.svg?fit=max\&auto=format\&n=vquUtcTAr7VDdwPB\&q=85\&s=2e6c8c64c80933fc511333069193c2fa)

已提交 offset 指向下一条待消费记录，LEO 指向下一条将写入的位置。查看一个 Group 在某个 Topic 上的整体堆积时，可以在按 Partition 去重并排除 `-1` 后，对 offset 距离求和；时间延迟取各 Partition 的最大值，不相加。

## 计算原理与局限

AutoMQ 周期性读取 Consumer Group 的已提交 offset 和 Partition 的 LEO，在同一轮采集中计算 offset 距离。时间延迟则利用写入和读取过程中采样的 `(offset, timestamp)`，通过内存中的稀疏参考点估算已提交 offset 的 timestamp。

Topic 使用 `LogAppendTime` 时，时间延迟约为当前时间与该估算 timestamp 的差。使用 `CreateTime` 时，指标反映消息时间戳的跨度，不等于消息距当前时间的年龄。

这些指标用于观察趋势和定位堆积，不能当作精确的待消费消息数或端到端消费延迟。Compaction、事务和 offset 空洞会影响 offset 距离与实际消息数的对应关系；采样和插值会影响时间估算。

Offset 指标为 `-1` 表示本轮无法获取 LEO；时间指标为 `-1` 还可能是缺少可用的 timestamp 参考点。`-1` 不能视为零堆积。没有时间序列时，还应检查该 Group 是否提交过 offset，以及指标采集是否正常。

## 用于大盘和告警

你可以将这两个指标接入 Grafana 等监控系统，按 Group、Topic 或 Partition 配置大盘，并根据业务可接受的堆积程度设置告警阈值。配置 Group 级视图时，offset 距离按 Partition 求和，时间延迟取最慢 Partition；同时关注 `-1`，避免未知值被汇总结果掩盖。

例如：

* **大盘：** 查看 `order-processor` Group 消费 `orders` Topic 的情况时，分别展示各 Partition offset 距离之和、最大估算时间延迟，以及时间延迟为 `-1` 的 Partition 数量。汇总值升高后，可以下钻到具体 Partition。
* **告警：** 如果 `orders` 使用 `LogAppendTime`，且业务希望在估算时间延迟超过 5 分钟时收到预警，可以在最慢 Partition 的时间延迟持续 5 分钟高于 `300000` 毫秒时触发告警。再为持续出现的 `-1` 单独设置告警，避免无法估算时误以为延迟正常。

指标的采集方式和现成的大盘模板参见 [Prometheus 监控与报警](https://docs.automq.com/zh/automq-cloud/monitoring-alert/monitoring-alert-via-prometheus.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.