---
title: "Alert when a consumer falls behind · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/consuming-events/consumer-lag
id: EVT-13
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1030
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Alert when a consumer falls behind

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Consuming events](https://agentwranglers.se/playbook/events/consuming-events.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-13
- Level: Recommended
- Chapter: [Consuming events](https://agentwranglers.se/playbook/events/consuming-events.md)
- Rule: Measure each consumer group's lag on every partition or queue, as messages behind and as the age of the oldest unread message. Alert before the age passes the delay the business accepts.
- Check: Each consumer group has a lag alert with a written time limit. Stop one consumer on staging while the producer runs. The alert fires before the limit, and it names the group and the partition.
- How: A stuck consumer raises no error. The broker keeps taking messages, and the backlog grows until a customer notices a missing email. Lag in messages is the newest offset minus the committed offset. Lag in time says more, because a busy partition can hold 10,000 messages that are 2 seconds old. Export both per group and per partition, for example with a lag exporter or the broker's own metrics. Alert on time, from the delay each consumer promises, such as 5 minutes for order emails. A lag that grows on one partition only points at a hot key, as [Choose the partition key for the order you need](https://agentwranglers.se/playbook/events/publishing-events/partition-keys.md) explains. Job queues follow [Alert on the age of the oldest waiting job](https://agentwranglers.se/playbook/operations/alerts-and-on-call/queue-age.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
# Prometheus alert on consumer lag in seconds, from a lag exporter
- alert: OrderEmailsConsumerBehind
  expr: max by (group, partition) (kafka_consumergroup_lag_seconds{group="order-emails"}) > 300
  for: 2m
  labels: { severity: page }
  annotations: { summary: "order-emails is {{ $value }}s behind on partition {{ $labels.partition }}" }
```

### Python example

```python
def lag_seconds(newest_timestamp_ms: int, committed_timestamp_ms: int) -> float:
    return max(0, newest_timestamp_ms - committed_timestamp_ms) / 1000

MAX_LAG_SECONDS = 300
if lag_seconds(newest, committed) > MAX_LAG_SECONDS:
    alert("order-emails consumer is behind", partition=partition)
```

### JavaScript example

```js
const MAX_LAG_SECONDS = 300;

export function checkLag({ group, partition, newestTimestampMs, committedTimestampMs }) {
  const lagSeconds = Math.max(0, newestTimestampMs - committedTimestampMs) / 1000;
  if (lagSeconds > MAX_LAG_SECONDS) alert(`${group} is ${lagSeconds}s behind on partition ${partition}`);
}
```

## Sources

- [Apache Kafka design, the consumer position](https://kafka.apache.org/43/design/design/)

## Related rules

- EVT-9 [Choose the partition key for the order you need](https://agentwranglers.se/playbook/events/publishing-events/partition-keys.md) in Integration and events
- OPS-67 [Alert on the age of the oldest waiting job](https://agentwranglers.se/playbook/operations/alerts-and-on-call/queue-age.md) in Operations and observability

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/events/consuming-events/consumer-lag">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Don't rely on event order](https://agentwranglers.se/playbook/events/consuming-events/event-order.md)
- Next: [Keep events long enough to replay them](https://agentwranglers.se/playbook/events/consuming-events/event-replay.md)
- [Consuming events](https://agentwranglers.se/playbook/events/consuming-events.md)