> ## 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.

# Monitor consumer lag

> Understand AutoMQ consumer lag metrics, how they are calculated, and when to use them.

## What consumer lag means

Consumer lag occurs when a consumer group's committed position falls behind writes to a topic. An offset difference alone does not tell you how late the data is: the same difference can represent different delays at different write rates.

For consumer groups using the Kafka classic group protocol, AutoMQ BYOC data plane (version 5.5.0 and later) provides offset distance and estimated time lag metrics.

## Metrics and dimensions

Both metrics have `group`, `topic`, and `partition` labels. Each series describes one consumer group's position in one topic partition.

| Metric | Meaning and calculation | Unit |
| - | - | - |
| `consumer_offset_lag_count` | The partition's log end offset (LEO) minus the consumer group's committed offset, clamped to `0` if negative. | offsets |
| `consumer_estimated_time_lag_milliseconds` | The estimated time lag for the partition, based on an estimated timestamp at the committed offset. | milliseconds |

![The upper offset axis shows Offset Lag of 30 for one partition; the lower time axis shows an estimated time lag of about 5 minutes with LogAppendTime](https://mintcdn.com/automq/okZPgpSeK--UqMcO/automq-cloud/monitoring-alert/monitor-consumer-lag/consumer-lag-metrics.svg?fit=max\&auto=format\&n=okZPgpSeK--UqMcO\&q=85\&s=dd8333b38cfe758ec91e44f967392e57)

The committed offset points to the next record to consume. LEO points to the next position to be written. For a group and topic view, deduplicate by partition and exclude `-1` before summing offset distances. Take the maximum time lag across partitions; do not add time lags together.

## Calculation and limitations

AutoMQ periodically reads the group's committed offset and the partition's LEO, then calculates their difference within one collection round. To estimate time lag, it samples `(offset, timestamp)` pairs during writes and fetches. Sparse reference points held in memory provide an estimated timestamp for the committed offset.

For topics using `LogAppendTime`, time lag is approximately the difference between the current time and that estimated timestamp. With `CreateTime`, the metric reflects a span of record timestamps, not the age of the data relative to the current time.

Use these metrics to observe trends and locate backlog. They are not exact counts of records waiting to be consumed or precise end-to-end consumption delay. Compaction, transactions, and offset gaps affect the relationship between offset distance and record count. Sampling and interpolation affect the time estimate.

Offset lag is `-1` when LEO is unavailable; time lag can also be `-1` when usable timestamp reference points are missing. Do not treat `-1` as zero lag. If a series is missing, also check whether the group has committed an offset and whether metrics are being collected.

## Use the metrics in dashboards and alerts

You can use these metrics in Grafana or another monitoring system to build group, topic, or partition views and set alert thresholds based on your application's acceptable lag. For group views, sum offset distances across partitions and use the slowest partition's time lag. Monitor `-1` values as well so that unknown results do not disappear in an aggregate.

For example:

* **Dashboard:** To monitor the `order-processor` group on the `orders` topic, show the sum of partition offset distances, the maximum estimated time lag, and the number of partitions with a time lag of `-1`. If an aggregate rises, drill down to the affected partitions.
* **Alert:** If `orders` uses `LogAppendTime` and you want an early warning when estimated time lag exceeds 5 minutes, alert when the slowest partition remains above `300000` milliseconds for 5 minutes. Alert separately on persistent `-1` values so an unavailable estimate does not appear healthy.

For metric collection and a dashboard template, see [Prometheus monitoring and alerts](https://docs.automq.com/automq-cloud/monitoring-alert/monitoring-alert-via-prometheus.md).


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