Redis Streamの深淵：`XTRIM`とメモリ限界突破のアーキテクチャ
こんにちは。テクニカルリードの私だ。
今日のコードレビューで、あるジュニアエンジニアが書いたRedis Streamのコードに目が止まった。
レビュー対象のコード（アンチパターン）
redis_client.xadd(“system:events”, {“payload”: data})
Streamが肥大化しないように毎回トリムしているつもり
redis_client.xtrim(“system:events”, maxlen=10000)
「動くからいいか」で済ませていないか？ この実装の裏で何が起きているか、あなたには説明できるだろうか？
毎回の書き込みに対して厳密な `MAXLEN 10000` を指定して `XTRIM` を叩く。これは、自らCPUキャッシュをヒットさせず、常にメモリのゴミ掃除をCPUに強いる最悪のパフォーマンスハックだ。
今回は、Redis Streamの生命線である `XTRIM`コマンド の深部を暴く。メモリ効率化、近似削除（`~`）のメカニズム、そしてプロダクション環境で事故らないための設計パターンを叩き込む。
—
1. `XTRIM` の本質：なぜ Stream は肥大化してはいけないのか
Redis Streamは、内部的には「基数ツリー（Radix Tree）」と「マクロノード（Listpack）」の組み合わせで構築されている。Append-onlyのログ構造を持つため、何もしなければデータは無限に蓄積され、最終的には物理メモリ（RAM）を食いつぶしてOOM（Out of Memory）を引き起こすか、スワップアウトによる致命的なレイテンシスパイクを引き起こす。
ここで登場するのが `XTRIM` だ。
Streamの長さを強制的に、あるいは緩やかに切り詰め、メモリフットプリントを一定の境界内に押し込める。しかし、その内部挙動を理解していないと、Redisのシングルスレッドを完全にブロックするボトルネックを作り出すことになる。
—
2. 厳密削除 vs 近似削除 (`~` オプションの真実)
`XTRIM` を語る上で避けて通れないのが、近似削除フラグである `~` (Tilde) だ。
A. 厳密な削除 (`MAXLEN 10000`)
指定したサイズに正確に一致させる。
XTRIM mystream MAXLEN 10000
- 裏側の動き: 厳密に10,000件を超える古いエントリをマクロノード単位、さらにはエントリ単位で完全にスキャンし、メモリから解放する。
- 代償: Streamが数百万件規模に肥大化した状態でこれをやると、O(N)のコスト（正確には削除するエントリ数に比例したコスト）が発生し、Redisのシングルスレッドが数ミリ秒〜数十ミリ秒間完全にフリーズする。数万件のクライアントリクエストがその間ブロックされるのだ。
B. 近似削除 (`MAXLEN ~ 10000`)
指定したサイズに「だいたい」合わせる。
XTRIM mystream MAXLEN ~ 10000
- 裏側の動き: Redis Streamの内部構造であるマクロノード（Listpack）の単位で削除判定を行う。1つのマクロノードには複数のエントリがパッキングされているため、「このノード丸ごと消すと10,000件を下回るが、残すと10,000件を超える」という境界において、ノード単位でバッサリと切り捨てる。結果として、10,050件や10,200件といった形で、指定値よりわずかに多いエントリが残る可能性がある。
- メリット: マクロノード単位の操作で済むため、計算量が劇的に減り、CPU負荷を最小限に抑えられる。
> 【リードリマインド】
> 特殊なコンプライアンス要件（「絶対に最新10,000件以外は保持してはならない」など）がない限り、実務では常に近似削除 (`~`) を使うべきだ。 メモリの数バイト・数キロバイトの厳密性よりも、P99レイテンシの安定性を優先するのがプロのアーキテクトである。
—
3. 実務で使える堅牢な設計パターン
冒頭のアンチパトリックなコード（毎回の `XTRIM`）は今すぐ捨ててほしい。では、どう設計すべきか。
パターンA：非同期・間引きバッチトリム（推奨）
すべての `XADD` ごとに `XTRIM` を走らせる必要はない。例えば、100回に1回、あるいはCronやバックグラウンドワーカーから確率的に、あるいは定期的に実行する。
import random
def safe_add_to_stream(redis_client, stream_key, data, maxlen=10000):
# データを追加
message_id = redis_client.xadd(stream_key, data)
# 毎回ではなく、約1%の確率でトリムを実行する（負荷分散）
# ※本番では専用の定期実行バッチ（CeleryやCron）を推奨するが、
# 簡易的なトラフィック分散としてはこの確率的アプローチも有効
if random.random() < 0.01:
# 必ず近似削除子 '~' を使用する
redis_client.xtrim(stream_key, maxlen=maxlen, approximate=True)
return message_id
パターンB：別プロセスによるクリーンアップ（大規模システム向け）
書き込みスレッドに一切のトリム負荷を与えたくない高スループットシステムでは、イベント駆動で別のワーカーを走らせるか、一定時間ごとに全対象Streamを巡回するメンテナンスタスクを配置する。
Redis CLIからの手動、またはスクリプトによる安全なメンテナンス例
50,000件を目安に近似削除
XTRIM my-high-throughput-stream MAXLEN ~ 50000
—
4. パフォーマンス上の注意点とトラブルシューティング
最後に、現場でトラブルを踏んだときに知っておくべき「急所」を共有する。
1. メモリフラグメンテーションの罠
`XTRIM` によってエントリが削除されても、Redisのメモリ allocator（jemalloc）の挙動により、OSへ即座にメモリが返還されないことがある。`INFO memory` で `mem_fragmentation_ratio` が異常に高い場合は、アクティブデフラグの有効化を検討せよ。
2. Consumer Group とのデッドロック（論理的矛盾）
`XTRIM` は、コンシューマーグループがどこまで読み進めているか（Last Delivered ID）を考慮せずに古いデータを容赦なく消し去る。もしコンシューマーが長期間ダウンしており、その間に `XTRIM` でデータがロストした場合、復旧時にメッセージが消失しているという致命的な障害（データロスト）に繋がる。
- 対策: `XTRIM` の閾値（`MAXLEN` や後発の `MINID`）は、コンシューマーの最大許容停止時間（Lag）を十分にカバーできる大きさに設計すること。
—
5. 結びの言葉
Redisは、そのデータ構造の特性を理解した上で使い倒して初めて真価を発揮する。
「動けばいい」という実装は、トラフィックが急増した瞬間にシステムを崩壊させる時限爆弾だ。
次回のコードレビューで、もし `XTRIM` が `~` なしで使われていたり、毎回の書き込みに紐づけられていたりしたら、この記事をそっと突きつけてやってほしい。
「我々のシステムでは、ミリ秒単位のレイテンシとメモリの調停をロジカルに制御する」——それこそが、エンジニアリングの美学だ。
コメント