はじめに：なぜ「人間が読むデバッグログ」を捨てなければならないのか
大規模なC/C++、あるいはRustやSwiftのプロジェクトにおいて、セグメンテーション違反や不規則なマルチスレッド競合に直面したとき、君たちはどうしているだろうか？
ブレークポイントを貼り、`thread backtrace`を叩き、流れていくコンソール出力をスクロールしながら必死にメモリダンプを目で追いかける――。もし未だにそんな「目視デバッグ」をCIパイプラインやローカル検証の主軸に置いているなら、今すぐその非効率なワークフローを破壊してほしい。
モダンなCI/CDパイプライン、そして真にスケーラブルな開発組織において、デバッグ情報は「人間が読むテキスト」ではなく「マシンが即座に解析・アグリゲーションできる構造化データ（JSON）」でなければならない。
今回は、LLVMプロジェクトの標準低レイヤデバッガである LLDB が内蔵する Python Scripting Bridge（`lldb` Python API） を極限までハックし、複雑なデバッグセッションの全貌を完璧な構造化JSONとして抽出、さらにCIパイプラインへと完全統合するための実践的アーキテクチャを伝授する。
—
LLDB Python Scripting Bridgeの内部アーキテクチャ
多くのエンジニアは、LLDBを「GDBの代替としてコマンドラインで操作するツール」としか認識していない。しかし、その実体は 「Pythonインタプリタをコアエンジンとして内蔵した、プログラム可能なプロセス操作ライブラリ」 である。
LLDBの内部では、SWIG（Simplified Wrapper and Interface Generator）を介して、C++で書かれたコアコンポーネント（Target, Process, Thread, Frame, ValueObject）がPythonオブジェクトとして完全に露出している。
[Target (バイナリとシンボル)]
└── [Process (実行中のプロセス)]
└── [Thread (スレッド)]
└── [Stack Frame (スタックフレーム)]
└── [ValueObject (ローカル変数・引数)]
この階層構造をPythonスクリプトからトラバースし、メモリ上の生データをJSONシリアライズ可能なプリミティブ型に変換することで、「任意の瞬間におけるプログラムの完全なスナップショット」 をJSONとして抽出することが可能になる。
—
実装：構造化JSONデバッグロガーの構築
ここからが本題だ。デバッグセッション中のクラッシュ時、あるいは特定のブレークポイントヒット時に、スレッドのバックトレース、全レジスタの値、ローカル変数を一網打尽にしてJSONとして吐き出すLLDB Pythonスクリプトを作成する。
プロジェクトのルートディレクトリに `.lldb/` ディレクトリを作成し、その中に `json_dump_bridge.py` を配置せよ。
`json_dump_bridge.py` （完全実装）
!/usr/bin/env python3
— coding: utf-8 —
import lldb
import json
import sys
from datetime import datetime
def __lldb_init_module(debugger, internal_dict):
“””
LLDBモジュールとしてロードされた際に自動実行される初期化関数。
カスタムLLDBコマンド ‘dump-state-json’ を登録する。
“””
debugger.HandleCommand(‘command script add -f json_dump_bridge.dump_execution_state dump-state-json’)
print(“[+] LLDB Plugin Loaded: ‘dump-state-json’ command is now available.”)
def value_to_json(valobj):
“””
LLDBのValueObjectを再帰的に走査し、JSONシリアライズ可能なPythonのプリミティブに変換する。
ポインタや複雑な構造体も安全に展開する。
“””
if not valobj.IsValid():
return {“error”: “Invalid ValueObject”}
data = {
“name”: valobj.GetName(),
“type”: valobj.GetTypeName(),
“summary”: valobj.GetSummary(),
“value”: valobj.GetValue()
}
# 構造体やクラス、配列の場合は子要素を再帰的に取得
children = []
if valobj.MightHaveChildren():
# 多重ループや巨大な配列によるフリーズを防ぐため最大32個までに制限
max_children = 32
num_children = valobj.GetNumChildren()
for i in range(min(num_children, max_children)):
child = valobj.GetChildAtIndex(i)
children.append(value_to_json(child))
if num_children > max_children:
children.append({“truncated”: f”Remaining {num_children – max_children} items omitted.”})
data[“children”] = children
return data
def dump_execution_state(debugger, command, result, internal_dict):
“””
現在のターゲットプロセスの全スレッド、フレーム、変数、レジスタ状態を
構造化JSONとしてダンプするLLDBカスタムコマンド。
“””
target = debugger.GetSelectedTarget()
if not target.IsValid():
result.SetError(“No valid target found in LLDB session.”)
return
process = target.GetProcess()
if not process.IsValid():
result.SetError(“No active process found. Run the program first.”)
return
session_data = {
“timestamp”: datetime.utcnow().isoformat() + “Z”,
“process_id”: process.GetProcessID(),
“threads”: []
}
# 全スレッドを走査
for thread in process:
thread_data = {
“thread_id”: thread.GetThreadID(),
“thread_index”: thread.GetIndexID(),
“name”: thread.GetName() or “unnamed”,
“stop_reason”: str(thread.GetStopReason()),
“frames”: []
}
# スタックフレームを走査
for frame in thread:
frame_data = {
“frame_index”: frame.GetFrameID(),
“pc”: hex(frame.GetPC()),
“function”: frame.GetFunctionName(),
“file”: frame.GetLineEntry().GetFileSpec().GetFilename(),
“line”: frame.GetLineEntry().GetLine(),
“arguments”: [],
“locals”: [],
“registers”: {}
}
# 引数（Arguments）の取得
for arg in frame.GetVariables(True, False, False, True):
frame_data[“arguments”].append(value_to_json(arg))
# ローカル変数（Locals）の取得
for local in frame.GetVariables(False, True, False, True):
frame_data[“locals”].append(value_to_json(local))
# 汎用レジスタ（Registers）の取得
registers = frame.GetRegisters()
for value_list in registers:
reg_category = value_list.GetName()
reg_dict = {}
for reg in value_list:
reg_dict[reg.GetName()] = reg.GetValue()
frame_data[“registers”][reg_category] = reg_dict
thread_data[“frames”].append(frame_data)
session_data[“threads”].append(thread_data)
# 出力先ファイルの指定（引数として渡された場合、またはデフォルト）
output_path = command.strip() if command else “lldb_crash_report.json”
try:
with open(output_path, “w”, encoding=”utf-8″) as f:
json.dump(session_data, f, indent=2, ensure_ascii=False)
result.AppendMessage(f”[+] Successfully exported structured debug state to: {output_path}”)
except Exception as e:
result.SetError(f”Failed to write JSON output: {str(e)}”)
—
チーム開発を加速する：設定ファイルのベストプラクティス
このPythonブリッジを毎回手動でインポートするのはナンセンスだ。チーム全体でこの仕組みを強制・共有するため、プロジェクトのルートに配置する `.lldbinit` のベストプラクティス構成を公開する。
プロジェクト専用 `.lldbinit`
セキュリティ上の理由から、LLDBはデフォルトでカレントディレクトリの `.lldbinit` の自動ロードを制限している。これを安全に有効化しつつ、自動的にスクリプトを読み込ませる。
==============================================================================
LLDB Project-Level Configuration (.lldbinit)
==============================================================================
セキュリティ警告を回避しつつ、プロジェクト固有のPythonスクリプトを自動ロード
settings set target.load-cwd-lldbinit true
クラッシュ時やアボート時に自動でJSONダンプスクリプトをトリガーするエイリアス
例: ‘run’ 中にプロセスが停止したら、自動的にダンプを実行して終了する
command alias dump-on-crash script import json_dump_bridge; json_dump_bridge.dump_execution_state(lldb.debugger, “ci_crash_dump.json”, lldb.SBCommandReturnObject(), {})
読みやすさのためのカスタムフォーマット設定
settings set stop-disassembly-count 5
スクリプトモジュールのロード
script import json_dump_bridge
さらに、ホームディレクトリ（`~/.lldbinit`）側には以下のグローバル設定を入れておき、セーフティネットを張る。
~/.lldbinit (Global)
ターゲット非依存の便利なエイリアス
command alias json-dump script json_dump_bridge.dump_execution_state(lldb.debugger, “manual_dump.json”, lldb.SBCommandReturnObject(), {})
—
CI/CDパイプラインへの完全統合：自動解析ワークフロー
このアプローチの真価は、「CI（GitHub ActionsやGitLab CIなど）環境でテストがクラッシュした際、人間がログを読む代わりに、JSONをパースしてSlackやDatadogに異常値を自動通知できる点」にある。
以下に、GitHub Actions上で非対話型LLDBを実行し、構造化JSONを生成、それをバリデーションするワークフローの神髄を示す。
`.github/workflows/debug_extractor.yml`
name: Automated LLDB JSON Extraction
on:
workflow_dispatch:
push:
branches: [ “main” ]
jobs:
debug-analysis:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Install LLDB and Python Dependencies
run: |
sudo apt-get update
sudo apt-get install -y lldb python3-lldb
- name: Build Target Binary with Debug Symbols
run: |
# デバッグシンボル(-g3 -O0)付きでビルド
g++ -g3 -O0 tests/faulty_sample.cpp -o faulty_binary
- name: Run LLDB in Batch Mode and Extract JSON
run: |
# LLDBをバッチモード(-b)で起動し、
# 1. スクリプトインポート
# 2. 実行(run) -> クラッシュ発生時にキャッチ
# 3. カスタムコマンドでJSONエクスポート
lldb -b \
-o “command script import ./.lldb/json_dump_bridge.py” \
-o “target create ./faulty_binary” \
-o “run” \
-o “dump-state-json ci_crash_report.json” \
-o “quit” || true
- name: Validate and Inspect JSON Artifact
run: |
if [ -f “ci_crash_report.json” ]; then
echo “[+] Crash report successfully generated. Inspecting structure…”
python3 -c ”
import json
with open(‘ci_crash_report.json’) as f:
data = json.load(f)
print(f’Process ID: {data[\”process_id\”]}’)
print(f’Total Threads: {len(data[\”threads\”])}’)
for t in data[‘threads’]:
print(f’ – Thread {t[\”thread_id\”]} ({t[\”name\”]}) stopped by: {t[\”stop_reason\”]}’)
”
else
echo “[-] No crash detected, normal execution finished.”
fi
- name: Upload Artifacts
uses: actions/upload-artifact@v4
with:
name: lldb-structured-json-report
path: ci_crash_report.json
—
生成される構造化JSONのサンプル
上記のスクリプトを実行すると、以下のような極めてリッチかつ完全な構造化JSONが出力される。このデータをDatadogやElasticsearchに流し込めば、過去のクラッシュ傾向のトレンド分析や、AI（LLM）による自動バグ修正エージェントへのインプットとして直結させることができる。
{
“timestamp”: “202X-10-24T12:34:56.789123Z”,
“process_id”: 48291,
“threads”: [
{
“thread_id”: 1,
“thread_index”: 0,
“name”: “main”,
“stop_reason”: “signal SIGSEGV: invalid address (fault address: 0x0)”,
“frames”: [
{
“frame_index”: 0,
“pc”: “0x401122”,
“function”: “process_payload(DataPacket)”,
“file”: “faulty_sample.cpp”,
“line”: 42,
“arguments”: [
{
“name”: “packet”,
“type”: “DataPacket “,
“summary”: “0x0000000000000000”,
“value”: “0x0”,
“children”: []
}
],
“locals”: [
{
“name”: “local_retry_count”,
“type”: “int”,
“summary”: “”,
“value”: “3”,
“children”: []
}
],
“registers”: {
“General Purpose Registers”: {
“rax”: “0x0000000000000000”,
“rsp”: “0x00007ffd521b3e10”,
“rip”: “0x0000000000401122”
}
}
}
]
}
]
}
—
テックリードからの提言：次のステップへ
この手法を導入したチームは、もはや「デバッグ画面に張り付くエンジニア」から解放される。クラッシュが発生した瞬間、CIは正確なJSON構造体を吐き出し、どのポインタがNULLだったのか、どのフレームのどのローカル変数が異常値だったのかをプログラムが自動判定する。
さらに発展させるならば、この生成された `ci_crash_report.json` を OpenAI API やローカルLLM（Llama 3等）にWebhook経由で自動送信し、「このクラッシュの原因と修正パッチを提案せよ」というプロンプトを叩く自動修復エージェントのパイプラインへと昇華させてほしい。
ツールに振り回されるな。ツールをプログラムし、開発のボトルネックをコードで殴り倒せ。君たちのプロジェクトの生産性が極限まで高まることを期待している。