［Redis匠の知見］SCRIPT DEBUGの罠：本番障害を防ぐLuaスクリプトデバッグの極意
こんにちは。システム全体のパフォーマンスとデータ整合性の境界線を守るチーフアーキテクトの私だ。
今日のコードレビューで、あるジュニアエンジニアが「Luaスクリプトの挙動がおかしいので、本番環境のレプリカで `SCRIPT DEBUG YES` を叩いてデバッグしました」と平然と報告してきた。
私の血圧が跳ね上がったのは言うまでもない。
RedisにおけるLuaスクリプトは、複数コマンドの原子性（Atomicity）を担保するための強力な武器だ。しかし、その内部機構やデバッグモードの特性を理解せずに扱うことは、「Loaded（装填済み）状態の銃を子供に渡す」に等しい。
今回は、Redisの隠れた諸刃の剣である `SCRIPT DEBUG` コマンドに焦点を当て、その深淵と、実務の現場で絶対に踏んではいけない地雷についてロジカルに解説しよう。
—
1. `SCRIPT DEBUG` とは何か？（内部アーキテクチャの真実）
まず、大前提を叩き込む。RedisのLuaスクリプトは、シングルスレッドのイベントループ上で完全にブロッキングしながら実行される。
`SCRIPT DEBUG` コマンドは、このLuaスクリプトの実行をデバッグするため、内部的にGDB（GNU Debugger）スタイルのネットワークデバッグモード（REPL）を有効化する設定コマンドだ。
SCRIPT DEBUG {YES | SYNC | NO}
- `YES`: 非同期デバッグモード。`redis-cli` との間にデバッグ用の独立した通信セッションを張り、ブレークポイントを設定しながらステップ実行を可能にする。
- `SYNC`: 同期デバッグモード。スクリプトの実行を完全に同期させ、デバッグセッションが終了するまでRedisサーバー全体のイベントループをストップさせる。
- `NO`: デバッグモードの無効化。
一見すると非常に便利な機能に思えるだろう。だが、これが本番環境においてどれほど凶悪な牙を隠し持っているか、アーキテクトなら脊髄反射で理解できなければならない。
—
2. 実践：デバッグセッションの作法と残酷な現実
まずは、安全な検証環境（Local / Sandbox）での挙動を見ておこう。
データの準備とスクリプトの投入
例えば、指定したキーの値をインクリメントし、閾値を超えたらログ（ここではRedisのログ）に出力するようなスクリプトを想定する。
— script.lua
local current = redis.call(‘GET’, KEYS[1])
if not current then
current = 0
end
local new_val = tonumber(current) + tonumber(ARGV[1])
redis.call(‘SET’, KEYS[1], new_val)
return new_val
これを`SCRIPT LOAD`でRedisに読み込ませ、SHA1ハッシュを得る。
デバッグの開始とステップ実行
ここで `SCRIPT DEBUG YES` を叩き、デバッグモードを有効化する。
1. デバッグモードを有効化（非同期）
127.0.0.1:6379> SCRIPT DEBUG YES
OK
2. EVALSHAでスクリプトを実行（別クライアント、または同セッション）
127.0.0.1:6379> EVALSHA 2d680… 1 my_counter 5
この瞬間、スクリプトを実行したクライアントはブロックされ、もう一つのターミナル（`redis-cli`）側でデバッガープロンプトが立ち上がる。
デバッガー側でのインタラクション例
-> line 2 of builtin: script, args: { ‘my_counter’, ‘5’ }
Jdb> l # ソースコードの表示
1 local current = redis.call(‘GET’, KEYS[1])
2 ->local current = redis.call(‘GET’, KEYS[1])
3 …
Jdb> n # 次の行へ進む (Next)
Jdb> c # 実行継続 (Continue)
ここまで見ると「よくできたデバッガーだ」と思うかもしれない。しかし、ここからがエンジニアの腕の見せ所だ。この裏で何が起きているかを知っているか？
—
3. なぜ `SCRIPT DEBUG` は「本番厳禁」なのか？（技術的負債とリスク）
設計レビューで私が厳しくチェックするポイントがここだ。以下の3つの理由により、`SCRIPT DEBUG`（特に `YES`）の本番利用は重大なインシデント誘発行為とみなす。
① Redis全体が「ハングアップ」する（シングルスレッドの呪縛）
`SCRIPT DEBUG YES` は、デバッグセッション中にRedisのイベントループを部分的に制御するが、根本的にRedisはシングルスレッドである。デバッグ待ち（開発者がブレークポイントでコーヒーを飲んでいる間）の最中、そのRedisインスタンスに対する他のすべてのクライアントからのリクエスト（GET, SET等）は完全にフリーズ（ブロック）する。
数秒のブレークポイントが、下流のマイクロサービス群に対して何千ものタイムアウト・雪崩式障害を引き起こすのだ。
② レプリケーションへの破壊的影響
マスター側で `SCRIPT DEBUG` を有効にしてスクリプトをステップ実行すると、マスターとレプリカ間のタイムラグが劇的に広がる。
特に `SYNC` モードを使用した場合、デバッグが終了するまでレプリカへのコマンド伝播が完全に止まるため、スプリットブレインやフェイルオーバー時のデータ乖離の温床となる。
③ コネクションとメモリのリークリスク
デバッグセッション中にクライアントが突然切断されたり、デバッガーのステート管理が狂ったりした場合、Redis内部のデバッグコンテキストが解放されずにメモリリークを引き起こすケースがある（古いバージョンでは特に顕著）。
—
4. チーフアーキテクトが推奨する「堅牢な設計パターン」
では、Luaスクリプトの挙動がおかしいとき、プロフェッショナルはどうデバッグすべきか？
本番環境やそれに準ずるステージング環境で安全に問題を切り分けるためのパターンを伝授する。
パターンA: ローカル環境（Docker）での完結
大原則として、Luaスクリプトのデバッグは本番データを持った環境で行ってはならない。
ローカルのDockerコンテナ上でミニマムなRedisを立ち上げ、その中で `redis-cli –eval` を用いて徹底的にテスト・デバッグする。
ローカルでスクリプトファイルを直接実行して検証する（これが最も安全）
redis-cli –eval script.lua my_counter , 5
この `–eval` オプションであれば、サーバー側の永続的なデバッグモードを汚染することなく、純粋に結果と戻り値を検証できる。
パターンB: スクリプト内ロギングの活用（`redis.log`）
Luaスクリプト内には、Redisのログ出力関数を組み込むことができる。デバッガーで止めるのではなく、ログに状態を出力させるのが実務的だ。
— デバッグ情報をRedisのシステムログに出力する
redis.log(redis.LOG_WARNING, “DEBUG: current value is ” .. tostring(current))
※注意: `redis.log` は多用するとI/Oネックになるため、検証目的が終わったら必ずコードから削除、またはフラグで無効化すること。Redisのログレベル設定（`loglevel`）が `notice` や `warning` の場合、`redis.log(redis.LOG_DEBUG, …)` は出力されない点にも注意せよ。
パターンC: ユニットテストの導入
複雑なロジックを持つLuaスクリプトは、手動デバッグに頼る時点で設計が肥大化している。
RedisのLuaをテストするための軽量なフレームワーク（例: LMochaなどのLua単体テスト環境）をCI/CDパイプラインに組み込み、純粋なLuaの関数としてロジックをテストしきることが、結果的に最も開発効率を高める。
—
5. まとめ
- `SCRIPT DEBUG` は、あくまでローカルまたは完全に隔離された検証環境でのみ許された一時的な診断ツールである。
- 本番環境で `SCRIPT DEBUG YES` や `SYNC` を叩くことは、システム全体の停止スイッチを押すのと同義であると心得よ。
- Luaスクリプトは「短く、アトミックで、副作用の少ない」記述に留め、複雑なビジネスロジックはアプリケーション層（Go, Rust, Node.js, Pythonなど）に委譲するのが現代の分散システムアーキテクチャの鉄則だ。
コードレビューで `SCRIPT DEBUG` の痕跡を見つけたら、私は容赦なくプルリクエストをフェイル（差し戻し）にする。
システムを預かるプロフェッショナルとして、背後にあるメカニズムをリスペクトし、安全で予測可能なコードを書こう。
コメント