データベース

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

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ドキュメントは、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のドキュメントの例では、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・パスワード設定で詳しく扱っています。

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

2026年11月時点の最新安定版はRedis 8.10.3(2026年10月26日公開)です。グループは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は、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を使います。2026年11月時点の最新は8.1.0(2026年7月30日公開)で、Python 3.10以上が必要です。書き方はRedis公式の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(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を使うと、ワーカー側から「このメッセージは処理不能」とFATALで返せます。ただしドキュメントの対応表ではRedis SoftwareとRedis Cloudが非対応となっており、使える環境は限定的です。退避先の監視や再投入の設計はデッドレターキュー(DLQ)とはで扱っています。

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

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

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

Streamsのエントリは、消さない限りメモリに残り続けます。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回目を無害にします。冪等の考え方は冪等性とはで解説しました。

発行側の重複には、Redis 8.6で入った冪等な追加(IDMP)が使えます。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の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の既定はappendonly no、有効にしたときの同期はappendfsync everysecなので、障害時には直近の書き込みを失う余地があります。決済のように1件も欠けられない記録は、Streamsだけに置かず、データベースへの書き込みを正とする設計にしてください。

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

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

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

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

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

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

Pub/Subの配信が最大1回になる条件はRedis Pub/Subの使い方で、Kafka側の構成はApache Kafkaとはで扱っています。

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

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

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

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

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

両者の設計思想の違いはRabbitMQとKafkaの違いでも比較しています。イベント連携をどの基盤に載せるか、既存のデータベースとの役割分担から見直したい場合は、データベース設計・移行支援で、現行のデータの流れの棚卸しから相談を受けています。

よくある質問

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の使い方と導入手順にまとめています。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.14 テックブログ Gitの脆弱性6件:CVE-2026-111760の再帰クローン対策と2.56.1への更新手順
  2. 2026.11.13 テックブログ 宝くじ公式サイト不正アクセス:4,436名の対象確認とパスワード再設定、変更された仕組み
  3. 2026.11.14 テックブログ ImageMagickの脆弱性VU#580079:policy.xmlの許可リスト設定と影響判定の手順
  4. 2025.08.05 コラム SXG(Signed Exchange)とは?仕組みと広まらなかった理由・2026年の撤去手順
  5. 2026.11.13 テックブログ KARTEの不正アクセス:JINS約1,829万件など利用企業の漏えい一覧と、タグ・配信・データ連携を確かめる手順【11月17日時点】

RELATED POSTS 関連記事

目次