---
title: "Redis Streamsの使い方：XADDとXREADGROUPのコンシューマグループ実装、ACK・再処理とKafkaとの使い分け【Redis 8.10系】"
url: "https://www.issoh.co.jp/tech/details/19926/"
published: 2026-11-17
updated: 2026-11-17
categories: ["データベース"]
publisher: "株式会社一創"
---

# Redis Streamsの使い方：XADDとXREADGROUPのコンシューマグループ実装、ACK・再処理とKafkaとの使い分け【Redis 8.10系】

Redis Streamsは、XADDで追加したメッセージをキーとして残し、複数のワーカーへ分担して配るためのデータ型です。Pub/Subと違い、受け手が落ちていてもメッセージは消えず、XACKで処理済みを伝えるまで「未完了」として追跡されます。この記事では、redis-cliとredis-py 8.1系で動く実装例を示しながら、Redis公式ドキュメントをもとにコンシューマグループの組み方を整理しました。後半では、止まったワーカーの分を引き取るXAUTOCLAIM、デッドレターへの退避、トリミングと冪等な追加、遅延の監視、Kafkaとの使い分けまで扱います。

## まとめ：Streamsは取りこぼせないイベント用、ACKと回収と冪等の3点で組む

Redis Streamsの配信は、XACKを使えば「少なくとも1回（at-least-once）」にできます。読んだだけのメッセージはPEL（未ACKの一覧）に残り、ワーカーが処理の途中で落ちても、別のワーカーがXAUTOCLAIMで引き取れます。

実装で外せないのは3点です。処理が終わったらXACKする、止まったワーカーの分を定期的にXAUTOCLAIMで回収する、同じメッセージが2回届いても結果が変わらないよう処理側を冪等にする。この3点がそろって初めて、Pub/Subにはない「消えない」性質が実際に効きます。

何か月分も保持して後から再生する用途や、1本のストリームで処理しきれない流量なら、Kafkaを選びます。既にRedisがあり、数時間から数日分のイベントを複数のワーカーで分担したいなら、Streamsで足ります。

## Redis Streamsの仕組み：エントリID・コンシューマグループ・PELの役割

Streamsで押さえる要素は、エントリID、コンシューマグループ、PELの3つです。この3つの関係が分かれば、コマンドの意味はほぼ読めます。

### エントリIDはミリ秒と連番の組で、XADDの追加はO(1)で単調に増える

[Redis公式のStreamsドキュメント](https://redis.io/docs/latest/develop/data-types/streams/)は、Streamsを追記専用のログ（append-only log）として説明しています。各エントリのIDは`ミリ秒時刻-連番`の形で、同じミリ秒に追加されたものは連番で区別される仕組みです。サーバーの時計が巻き戻っても、直前のエントリより小さいIDは振られません。

追加の計算量はO(1)です。IDが時刻順に並ぶため、「この時刻以降」のような範囲をXRANGEで取り出せます。1つのエントリはフィールドと値の組を複数持てるので、JSONを1つの値に詰めるより、`type`や`order_id`を別フィールドにしておくと、後からredis-cliで中身を確かめやすくなります。

### XREADとXREADGROUPの違い：全員に配るか、グループ内で分担するか

読み出し方は2通りです。XREADは、読んだ全員に同じエントリを返す読み方で、`tail -f`に近い動きをします。XREADGROUPは、コンシューマグループに属するワーカー同士でエントリを分け合う読み方です。

[XREADGROUPのドキュメント](https://redis.io/docs/latest/commands/xreadgroup/)の例では、A・B・Cの3件が届くと、一方のワーカーがAとCを、もう一方がBを受け取ります。1つのストリームに複数のグループを作れて、グループごとに読み進めた位置を別々に持つ設計です。通知用と集計用のように、同じイベントを用途別に全件処理させたいときは、グループを分けます。

### PELは配信済み未ACKの一覧で、XACKするまでIDと配信回数が残る

XREADGROUPで受け取ったエントリは、そのグループのPEL（Pending Entries List）に記録されます。PELに残るのは、エントリID、受け取ったワーカー名、最後に配信してからの経過時間、配信回数の4つです。

XACKを送るとPELから消えます。送らないままワーカーが落ちると、そのエントリは誰かが引き取るまでPELに残り続けます。逆に、XREADGROUPに`NOACK`を付けると読んだ時点でACK済みの扱いになり、PELに記録されません。取りこぼしを許せる用途以外では付けないでください。

## redis-cliでXADDからXACKまでを試す手順とXPENDINGの読み方

手元で動きを確かめるなら、Dockerで1台起動してredis-cliから打つのが早道です。Redis本体の起動手順は[RedisをDockerで動かす手順：compose.yamlでの永続化・redis.conf・パスワード設定](https://www.issoh.co.jp/tech/details/19855/)で詳しく扱っています。

### Redis 8.10をDockerで起動し、XGROUP CREATEでグループを作る

2026年11月時点の最新安定版は[Redis 8.10.3](https://github.com/redis/redis/releases/tag/8.10.3)（2026年10月26日公開）です。グループは[XGROUP CREATE](https://redis.io/docs/latest/commands/xgroup-create/)で作ります。

```
# Redis 8.10系を起動して redis-cli に入る
docker run -d --name redis-streams -p 6379:6379 redis:8.10
docker exec -it redis-streams redis-cli

# グループ billing を作る。ストリームが無ければ MKSTREAM で空のまま作る
XGROUP CREATE app:dev:orders billing $ MKSTREAM

# 注文イベントを2件追加する。* はIDの自動採番
XADD app:dev:orders * type order.placed order_id 1001
XADD app:dev:orders * type order.placed order_id 1002
```

XGROUP CREATEの`$`は「作った時点より後に届くものだけ配る」指定です。`0`にすると、ストリームに残っている過去分もすべてグループに配られます。同じ名前のグループが既にあると`BUSYGROUP`エラーが返るので、アプリの起動処理ではこのエラーだけを無視する書き方にします。

### XREADGROUPの>と0の違い：新着の受信と自分の未ACK分の読み直し

XREADGROUPの最後に渡すIDで、読む対象が変わります。`>`はグループ内の誰にもまだ配っていない新着、それ以外のIDはそのワーカー自身のPELにある未ACK分です。

```
# 新着を最大10件、無ければ5秒待つ
XREADGROUP GROUP billing worker-1 COUNT 10 BLOCK 5000 STREAMS app:dev:orders >

# 処理が終わったIDを確認済みにする（IDは上の結果に出たものを使う）
XACK app:dev:orders billing 1763340000000-0

# worker-1 の未ACK分を最初から読み直す
XREADGROUP GROUP billing worker-1 STREAMS app:dev:orders 0
```

公式ドキュメントは、クラッシュ後の再開手順として、まず`0`で自分のPELを読み、結果が空になったら`>`に切り替える流れを示しています。`0`を指定した読み出しでは`BLOCK`と`NOACK`は無視される仕様です。また、PELに残っているエントリがトリミングやXDELで消されていると、IDだけが返り、中身は`nil`になる点にも注意が要ります。

### XPENDINGで未ACK件数・アイドル時間・配信回数の3項目を確かめる

[XPENDING](https://redis.io/docs/latest/commands/xpending/)は、PELの中身を確かめるコマンドです。引数を省くと要約、範囲を付けるとエントリごとの明細が返ります。

```
# 要約：未ACKの総数、最小と最大のID、ワーカーごとの件数
XPENDING app:dev:orders billing

# 明細：ID、ワーカー名、最後の配信からのミリ秒、配信回数
XPENDING app:dev:orders billing - + 10
```

明細の3列目が大きいエントリは、受け取ったワーカーが止まっている可能性が高いものです。4列目の配信回数が何度も増えているなら、ワーカーではなくメッセージの中身に問題があると疑います。次の章で、この2つをそれぞれ回収と退避の判定に使います。

## redis-py 8.1系で書くコンシューマのPythonコードと回収処理

Pythonでは[redis-py](https://pypi.org/project/redis/)を使います。2026年11月時点の最新は8.1.0（2026年7月30日公開）で、Python 3.10以上が必要です。書き方は[Redis公式のredis-pyによるストリーミング実装ガイド](https://redis.io/docs/latest/develop/use-cases/streaming/redis-py/)に沿っています。

### 起動時に自分の未ACK分を処理してから新着を読むワーカーの書き方

ワーカーは、起動直後に自分のPELを片付け、そのあと新着の待ち受けに入ります。前回落ちたときに処理しかけていた分を、ここで拾い直せます。

```
# consumer.py（pip install "redis>=8.1"）
import redis

STREAM = "app:dev:orders"
GROUP = "billing"
CONSUMER = "worker-1"  # プロセスごとに一意の名前にする

# 返り値の形を固定するため RESP2 を明示する
r = redis.Redis(host="localhost", port=6379, decode_responses=True, protocol=2)

try:
    r.xgroup_create(STREAM, GROUP, id="$", mkstream=True)
except redis.exceptions.ResponseError as e:
    if "BUSYGROUP" not in str(e):
        raise

def handle(entry_id, fields):
    if fields is None:  # トリミング済みで中身が無い
        return
    print(entry_id, fields["type"], fields["order_id"])

def read_and_ack(start_id, block=None):
    resp = r.xreadgroup(GROUP, CONSUMER, {STREAM: start_id}, count=10, block=block)
    entries = resp[0][1] if resp else []
    for entry_id, fields in entries:
        handle(entry_id, fields)
        r.xack(STREAM, GROUP, entry_id)
    return entries

# 1. 自分の未ACK分が空になるまで処理する
while read_and_ack("0"):
    pass

# 2. 新着を5秒ずつ待ち受ける
while True:
    read_and_ack(">", block=5000)
```

XACKは処理の後に送ります。先にACKしてから処理すると、処理中に落ちた分がPELに残らず、Pub/Subと同じく消えてしまいます。発行側は`r.xadd(STREAM, {"type": "order.placed", "order_id": "1001"}, maxlen=100000, approximate=True)`のように、件数の上限を付けて追加するのが基本形です。

### XAUTOCLAIMで停止したワーカーの未ACK分を引き取る定期処理

ワーカーが落ちたまま戻らないと、その分はPELに残り続けます。[XAUTOCLAIM](https://redis.io/docs/latest/commands/xautoclaim/)（Redis 6.2から）は、指定したミリ秒以上放置されているエントリを、呼び出したワーカーの持ち分に移すコマンドです。

```
IDLE_MS = 60000  # 60秒以上ACKされていない分を引き取る

def reclaim():
    cursor = "0-0"
    while True:
        cursor, claimed, deleted = r.xautoclaim(
            STREAM, GROUP, CONSUMER, min_idle_time=IDLE_MS, start_id=cursor, count=100
        )
        for entry_id, fields in claimed:
            handle(entry_id, fields)
            r.xack(STREAM, GROUP, entry_id)
        for entry_id in deleted:
            print("中身が消えていたため処理できない", entry_id)
        if cursor == "0-0":
            break
```

返り値は、次回の開始位置、引き取ったエントリ、既にストリームから消えていたIDの3つです。3つ目はRedis 7.0で加わった要素で、これらのIDはPELからも取り除かれます。1回で走査するのはCOUNT（既定100）の10倍までなので、開始位置が`0-0`に戻るまで繰り返します。

公式ガイドは、各ワーカーが数秒ごとに自分宛てにXAUTOCLAIMを呼ぶ形を勧めています。新着の読み出しループで`0`を毎回読むと、未ACK分の放置時間がそのたびに0へ戻り、いつまでも回収の対象にならないためです。Redis 8.4以降なら、XREADGROUPに`CLAIM 60000`を付けて、新着の前に放置分を一緒に受け取る書き方もできます。

### 配信回数が5回を超えたらデッドレター用ストリームへ退避する判定

中身が壊れているメッセージは、誰が引き取っても処理に失敗し、XAUTOCLAIMのたびに配信回数だけが増えていきます。公式ドキュメントは、配信回数が決めた値に達したら別のストリームへ移して管理者に知らせる方法を、Streamsでのデッドレターの考え方として紹介しています。

```
MAX_DELIVERIES = 5

def move_poison():
    for p in r.xpending_range(STREAM, GROUP, min="-", max="+", count=100):
        if p["times_delivered"] < MAX_DELIVERIES:
            continue
        mid = p["message_id"]
        rows = r.xrange(STREAM, min=mid, max=mid)
        fields = rows[0][1] if rows else {}
        r.xadd(STREAM + ":dlq", {"src_id": mid, **fields})
        r.xack(STREAM, GROUP, mid)  # 元のグループからは外す
```

退避したあとは、元のグループでACKしてPELから外す手順です。Redis 8.8で入った[XNACK](https://redis.io/docs/latest/commands/xnack/)を使うと、ワーカー側から「このメッセージは処理不能」と`FATAL`で返せます。ただしドキュメントの対応表ではRedis SoftwareとRedis Cloudが非対応となっており、使える環境は限定的です。退避先の監視や再投入の設計は[デッドレターキュー（DLQ）とは](https://www.issoh.co.jp/tech/details/19037/)で扱っています。

## 本番で詰まらないためのMAXLENトリミング・冪等性・遅延監視の設定

開発環境で動いたStreamsが本番で問題になるのは、メモリの膨張、重複処理、気づかない遅延の3つです。いずれも設定とコードで先に手当てできます。

### MAXLEN \~の概算トリミングと、未ACK分のデータが消える落とし穴

Streamsのエントリは、消さない限りメモリに残り続けます。[XADD](https://redis.io/docs/latest/commands/xadd/)の`MAXLEN`で件数の上限を、Redis 6.2からの`MINID`でIDの下限を指定する方式です。`~`を付けると内部のまとまり単位で切る概算になり、指定より少し多く残る代わりに処理が軽くなります。

落とし穴は、トリミングがPELを見ない点です。既定の`KEEPREF`では、未ACKのエントリも上限を超えれば中身が消え、PELにはIDだけが残ります。処理が遅れたワーカーが受け取るのは、中身の無いIDです。Redis 8.2からは、全グループがACKしたものだけを消す`ACKED`を指定できます。

```
# 全グループがACK済みのものだけを対象に、概算で10万件に保つ（Redis 8.2以降）
XADD app:prod:orders ACKED MAXLEN ~ 100000 * type order.placed order_id 1001
```

`ACKED`は、ACKされない分が上限を超えて溜まると、そこでトリミングが止まります。メモリを守るか処理を守るかの選択なので、遅延の監視と組み合わせて使ってください。

### at-least-onceの重複に備える処理側の冪等化とXADDのIDMP

XAUTOCLAIMで引き取ったメッセージは、元のワーカーが処理を終えてACKの直前に落ちた分かもしれません。公式ガイドも、Streams単独では「ちょうど1回（exactly-once）」にならないため、処理側を冪等にするよう求めています。注文IDをキーにした一意制約やupsert、処理済みIDの記録などで、2回目を無害にします。冪等の考え方は[冪等性とは](https://www.issoh.co.jp/tech/details/13382/)で解説しました。

発行側の重複には、Redis 8.6で入った[冪等な追加（IDMP）](https://redis.io/docs/latest/develop/data-types/streams/idempotency/)が使えます。XADDの応答を受け取る前に回線が切れて再送した場合でも、同じ発行元IDとメッセージIDの組なら、新しいエントリを作らず元のIDを返します。

```
# 発行元 order-api のメッセージ ord-1001 を1回だけ追加する
XADD app:prod:orders IDMP order-api ord-1001 * type order.placed order_id 1001

# 重複を判定する期間（秒）と、発行元ごとに覚えておく件数
XCFGSET app:prod:orders IDMP-DURATION 300 IDMP-MAXSIZE 1000
```

既定の保持は100秒・100件で、それぞれ最大86,400秒と10,000件まで広げられます。ドキュメントには、スループットが2〜5%下がると書かれています。

### XINFO GROUPSのlagとpendingで処理遅れとACK漏れを見分ける

監視には[XINFO GROUPS](https://redis.io/docs/latest/commands/xinfo-groups/)の2項目を使います。`lag`はまだグループに配っていない件数、`pending`は配ったがACKされていない件数です。

```
XINFO GROUPS app:prod:orders
XINFO CONSUMERS app:prod:orders billing
```

公式ガイドの読み分けは明快です。lagが増え続けるなら、発行にワーカーの処理が追いついていないので台数を足します。pendingが増え続けるなら、ワーカーは受け取っているのにACKしていないので、処理中のクラッシュかACK漏れを疑います。トリミングでエントリが消えた直後などはlagがNULLになる場合があり、その間は値が取れない前提でアラートを組んでください。

### AOFのfsync設定とフェイルオーバーで直近の追加が失われうる範囲

「消えない」のはRedisのプロセスが生きている間の話です。ストリームとグループの状態はAOF・RDB・レプリカに伝わりますが、公式ドキュメントは注意点を3つ挙げています。メッセージの永続性が要るならAOFを強いfsync設定で使うこと、非同期レプリケーションではフェイルオーバー後に一部が欠けうること、WAITで伝播を待っても欠ける可能性はゼロにならないことです。

[redis.conf 8.10.3](https://github.com/redis/redis/blob/8.10.3/redis.conf)の既定は`appendonly no`、有効にしたときの同期は`appendfsync everysec`なので、障害時には直近の書き込みを失う余地があります。決済のように1件も欠けられない記録は、Streamsだけに置かず、データベースへの書き込みを正とする設計にしてください。

## Redis StreamsとKafka・Pub/Subの使い分け：保持期間と順序で決める

判断の軸は、どれだけの期間を保持するか、同じ対象のイベント順序をどこまで守るかの2つです。

### Kafkaのパーティションと違い、1キーのStreamsは自動で分割されない

コンシューマグループという用語はKafkaから借りたものですが、公式ドキュメントは実装がまったく別物だと断っています。[Kafkaの公式ドキュメント](https://kafka.apache.org/44/getting-started/introduction/)が示すとおり、Kafkaはトピックをパーティションに分け、同じパーティションのイベントは書き込み順に読まれる仕組みです。保持期間もトピックごとに設定します。

Redis Streamsの1キーは、自動では複数のノードに分かれません。グループ内の分担は「手が空いたワーカーに渡す」方式なので、1つのストリームを複数のワーカーで読むと、同じ注文のイベントが順序どおりに処理される保証はありません。順序が要るなら、注文IDなどで複数のキーに分け、キーごとに担当ワーカーを固定します。Redis Clusterでキーを分散する仕組みは[Redis Clusterの構築手順](https://www.issoh.co.jp/tech/details/19853/)で解説しています。

| 観点       | Redis Pub/Sub | Redis Streams     | Kafka              |
| -------- | ------------- | ----------------- | ------------------ |
| メッセージの保存 | 保存しない         | メモリに保存（上限は自分で決める） | ディスクに保存（期間はトピックごと） |
| 配信保証     | 最大1回          | ACKで少なくとも1回       | コミット方式で選ぶ          |
| 分割       | なし            | キーを分けて自分で分割       | パーティションで分割         |
| 順序       | チャネル単位        | 1ワーカーで読む場合のみ      | パーティション内で保証        |
| 運用の追加    | 既存Redisで足りる   | 既存Redisで足りる       | 専用クラスタが要る          |

Pub/Subの配信が最大1回になる条件は[Redis Pub/Subの使い方](https://www.issoh.co.jp/tech/details/19865/)で、Kafka側の構成は[Apache Kafkaとは](https://www.issoh.co.jp/tech/details/7563/)で扱っています。

### Streamsを採用する条件：既にRedisがあり、保持は数日分で足りる

Streamsを選んでよいのは、次の条件がそろうときです。既にRedisを運用していて新しい基盤を増やしたくない、保持するのはメモリに載る数時間から数日分、流量が1つのRedisで受けきれる範囲に収まる。注文確定後のメール送信や在庫の引き当て、外部APIへの連携など、ワーカー数台で分担する非同期処理が典型例です。

リトライ間隔や遅延実行まで自前で書きたくない場合は、Redisを土台にしたジョブキューの[BullMQ](https://www.issoh.co.jp/tech/details/17289/)のようなライブラリを先に検討してください。Streamsはその下の層にあたり、自由度が高い分、回収と退避を自分で書く必要があります。

### Streamsを採用しない場面：長期保存・再生前提の分析基盤と大量配信

イベントを何か月も保持して後から何度も読み直す、分析基盤や検索インデックスへ同じイベントを多数の系統に流す、といった用途はKafkaに任せます。メモリに全件を抱えるStreamsでは、保持期間を延ばすほど費用が膨らむためです。1件も失えない会計記録を、AOFの設定だけを頼りにStreamsへ置く設計も避けます。

両者の設計思想の違いは[RabbitMQとKafkaの違い](https://www.issoh.co.jp/tech/details/15305/)でも比較しています。イベント連携をどの基盤に載せるか、既存のデータベースとの役割分担から見直したい場合は、[データベース設計・移行支援](https://www.issoh.co.jp/service/system/database/)で、現行のデータの流れの棚卸しから相談を受けています。

## よくある質問

Redis Streamsについて、実装の途中でよく出る疑問に答えます。

### XREADGROUPで読んだメッセージをACKし忘れるとどうなりますか？

メッセージはPELに残り続けます。新着の配信は止まりませんが、PELが膨らんでメモリを使い、XINFO GROUPSのpendingが増え続けます。そのワーカーが`0`で読み直すかXAUTOCLAIMで誰かが引き取るまで、処理済みかどうかをRedisは判断できません。処理の成功後に必ずXACKを送り、pendingの増加をアラートにしておくと早く気づけます。

### Redis Streamsでメッセージをちょうど1回だけ処理できますか？

Streams単独ではできません。XACKを送る前にワーカーが落ちると、そのメッセージは別のワーカーに再配信されるため、同じ処理が2回走る可能性が残ります。公式ガイドも、冪等キーや一意制約で処理側を冪等にするよう求めています。発行側の二重追加はRedis 8.6のIDMPで防げますが、処理側の重複までは防げません。

### Redis Streamsのメッセージを「24時間分だけ残す」設定はありますか？

Kafkaのような時間指定の保持設定はありません。IDの先頭がミリ秒時刻なので、24時間前の時刻を計算して`XTRIM app:prod:orders MINID ~ 1763250000000-0`のように古いものを切ります。定期実行のジョブで回すか、XADDのたびに`MINID`を付けます。`~`付きの概算なので、境界の少し前のエントリが残る点は許容してください。

### BullMQやCeleryのようなジョブキューとStreamsはどう違いますか？

BullMQなどのジョブキューは、リトライ回数、待ち時間の段階的な延長、遅延実行、優先度といった機能を最初から持っています。Streamsは土台の部品で、こうした機能はXAUTOCLAIMや配信回数を使って自分で組む設計です。ジョブ処理が目的ならジョブキューを、同じイベントを複数のグループに配りたい、ログとして読み直したいならStreamsを選びます。

### ValkeyやElastiCacheでも同じコマンドが使えますか？

XADD、XREADGROUP、XACK、XAUTOCLAIMなど基本のコマンドは、Redis 7.2系から分かれたValkeyでも共通です。一方、XREADGROUPのCLAIM（8.4）、IDMP（8.6）、XNACK（8.8）はRedis 8系のドキュメントに載る新しい機能なので、Valkeyやマネージドサービスで使えるかは各サービスの資料で確かめてください。Valkey側のStreamsの使い方は[Valkeyとは？Redisとの違い・Streamsの使い方と導入手順](https://www.issoh.co.jp/tech/details/9652/)にまとめています。

## 関連記事

- [Redisとは：仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順](https://www.issoh.co.jp/tech/details/18876/)：Redis本体の仕組みとデータ型
- [Redis Pub/Subの使い方：PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け](https://www.issoh.co.jp/tech/details/19865/)：保存しない配信との比較
- [BullMQとは？v6のPostgreSQL対応・リトライとワーカー運用を実装者目線で解説](https://www.issoh.co.jp/tech/details/17289/)：Redisを土台にしたジョブキュー
- [デッドレターキュー（DLQ）とは：退避条件・再処理・監視の設計とSQS・Pub/Sub・Service Busの設定例](https://www.issoh.co.jp/tech/details/19037/)：処理できないメッセージの退避設計
- [Apache Kafkaとは？仕組み・ユースケースと最新版4.4のKRaft構成を実装視点で解説](https://www.issoh.co.jp/tech/details/7563/)：長期保存と大量配信を担う基盤

---

出典: [Redis Streamsの使い方：XADDとXREADGROUPのコンシューマグループ実装、ACK・再処理とKafkaとの使い分け【Redis 8.10系】](<https://www.issoh.co.jp/tech/details/19926/>)（株式会社一創）
