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の使い方と導入手順にまとめています。
関連記事
- Redisとは:仕組みとデータ型・Redis 8.10系の新機能とライセンス、Dockerで動かす手順:Redis本体の仕組みとデータ型
- Redis Pub/Subの使い方:PUBLISHとSUBSCRIBEの実装例、メッセージ消失の対策とStreamsとの使い分け:保存しない配信との比較
- BullMQとは?v6のPostgreSQL対応・リトライとワーカー運用を実装者目線で解説:Redisを土台にしたジョブキュー
- デッドレターキュー(DLQ)とは:退避条件・再処理・監視の設計とSQS・Pub/Sub・Service Busの設定例:処理できないメッセージの退避設計
- Apache Kafkaとは?仕組み・ユースケースと最新版4.4のKRaft構成を実装視点で解説:長期保存と大量配信を担う基盤