XdebugトレースをWebSequenceDiagramsで完全自動化する：レガシーPHPの構造的解剖とCI/CD統合アーキテクチャ
レガシーなPHPアプリケーション、特にドキュメントが完全に欠落し、数世代前の開発者たちが残したスパゲッティコードの海に放り込まれたとき、シニアエンジニアが最初に直面する絶望は「処理フローの不可視性」である。数千行に及ぶエントリーポイント、無秩序にインスタンス化されるサードパーティ製ライブラリ、そして暗黙的に依存し合うグローバルステート。
デバッガをアタッチして1ステップずつ追うようなアプローチは、マクロな構造を把握するにはあまりにも低解像度であり、時間的損失が大きい。
我々が求めるべきは、「実行時のコールスタックをキャプチャし、それを瞬時に人間が認知可能なシーケンス図へと昇華させる自動化パイプライン」である。
本稿では、Xdebugの関数トレース（Function Trace）出力を低レイヤからハックし、WebSequenceDiagramsのAPIを叩くCLIスクリプトによって、Docker環境およびCI/CDパイプライン上で完全自動図解化するアーキテクチャを解説する。
—
1. Xdebugトレース内部構造とメモリ最適化の極意
Xdebugの関数トレース機能（`xdebug.mode = trace`）は、PHPの実行エンジンであるZend Engineの関数呼び出しフックを利用して、すべての関数/メソッドの入退室、引数、メモリ消費量、実行時間をシリアルに出力する。
しかし、デフォルト設定のまま大規模なフレームワーク（SymfonyやLaravel、あるいは古のZend Framework 1）でトレースを有効化すると、数秒で数十MBから数百MBのテキストログが生成され、I/Oボトルネックによってコンテナ自体がフリーズするか、メモリが枯渇する。
限界突破のための `php.ini` チューニング
実戦投入にあたっては、トレースの粒度を制御し、パフォーマンスペナルティを最小限に抑えるための厳格な設定が必要となる。
[xdebug]
; デバッグモードとトレースモードを明示的に有効化
xdebug.mode = trace
xdebug.start_with_request = trigger
; トレースファイルの出力先をホストマウント可能な専用ディレクトリへ固定
xdebug.output_dir = “/var/log/xdebug_traces”
; ログの肥大化を防ぎつつ、オブジェクト指向のコールツリーを追跡できるフォーマットを指定
; 1: フル情報（関数名、ファイル名、行番号、メモリ使用量、返り値など）
xdebug.trace_format = 1
; トレーシング時のオーバーヘッドを削減するため、不要な変数の詳細出力を抑制
xdebug.collect_params = 1
xdebug.collect_return = 1
; 巨大なサードパーティライブラリ（vendor/）をトレース対象から除外するブラックリスト戦略
; ※Xdebug 3では関数名やファイルパスの動的フィルタリングをスクリプト側で行うのが定石
アーキテクトの知見:
Xdebug 3のトレースログ（`trace_format = 1`）は、タブ区切りのフラットなテキストとして出力される。ここには「どの関数からどの関数が呼ばれたか（親・子の関係）」がインデントやコール深度（Level）として記録されている。このバイナリに近い生データをパースし、シーケンス図のライフラインに変換するトランスレータが鍵となる。
—
2. Docker環境におけるトレース自動収集の要塞化
開発者のローカル環境やCI環境（GitHub Actions / GitLab CI）で一貫して動作するDocker Compose構成を構築する。ここでは、PHP-FPMまたはCLIコンテナと、トレース解析スクリプトを実行するサイドカー的な役割を兼ねた構成をとる。
`docker-compose.yml` の実践的設計
version: ‘3.8’
services:
app:
build:
context: .
dockerfile: docker/php/Dockerfile
volumes:
# アプリケーションコードのマウント
- ./:/var/www/html
# Xdebugトレース専用の共有ボリューム（ホストとコンテナ間でログを即座に同期）
- xdebug_traces:/var/log/xdebug_traces
environment:
- XDEBUG_MODE=trace
- XDEBUG_TRIGGER=1
- PHP_IDE_CONFIG=serverName=docker-local
networks:
- app-net
# トレースログを監視し、自動でシーケンス図へ変換するアナライザーサービス
tracer:
build:
context: .
dockerfile: docker/tracer/Dockerfile
volumes:
- xdebug_traces:/var/log/xdebug_traces
- ./docs/sequences:/var/www/html/docs/sequences
depends_on:
- app
networks:
- app-net
command: [“python3”, “/opt/tracer/watch_and_convert.py”]
volumes:
xdebug_traces:
driver: local
networks:
app-net:
driver: bridge
—
3. テキストログからシーケンス図へ：Pythonによる変換エンジン
Xdebugの生トレースログを、WebSequenceDiagramsが解釈可能なDSL（Domain Specific Language）へ変換するコアスクリプトを実装する。
単にテキストを置換するのではなく、「フレームワーク固有のフレーム（IlluminateやSymfonyの内部処理など）を自動的にフィルタリングし、業務ロジックのクラス間連携のみを抽出する」高度なパース処理を実装する。
`watch_and_convert.py` （コア変換ロジック）
import os
import re
import time
import requests
import glob
TRACE_DIR = “/var/log/xdebug_traces”
OUTPUT_DIR = “/var/www/html/docs/sequences”
API_URL = “https://www.websequencediagrams.com/index.php”
def parse_xdebug_trace(filepath):
“””
Xdebug trace_format = 1 のログをパースし、オブジェクト間のメッセージパッシングを抽出する
“””
calls = []
# ライフラインの重複を防ぐためのアクティブクラス追跡
# 簡易正規表現パターン（関数名、呼び出し元、呼び出し先をキャプチャ）
# 例: 0.123 1024 -> App\Services\OrderService->process()
pattern = re.compile(r”^\s([\d\.]+)\s+(\d+)\s+->\s+([a-zA-Z0-9_\\\:]+)\(“)
with open(filepath, ‘r’, encoding=’utf-8′, errors=’ignore’) as f:
for line in f:
match = pattern.search(line)
if match:
timestamp, memory, func_name = match.groups()
# フレームワークの内部処理やビルトイン関数をノイズとして除外
if “Illuminate\\” in func_name or “Symfony\\” in func_name or “PDO” in func_name:
continue
if “->” in func_name or “::” in func_name:
parts = re.split(r’->|::’, func_name)
caller = “Client”
callee = parts[0]
method = parts[1] if len(parts) > 1 else “unknown”
calls.append((caller, callee, method))
return calls
def generate_dsl(calls):
“””
抽出したコール履歴から WebSequenceDiagrams 用の DSL を生成
“””
dsl_lines = [“title Auto-Generated Sequence Diagram from Xdebug Trace”]
# 冗長な呼び出しをまとめつつ、シーケンスの順序を維持
seen_interactions = set()
for caller, callee, method in calls:
if caller != callee:
interaction = f”{caller}->{callee}: {method}()”
if interaction not in seen_interactions:
dsl_lines.append(interaction)
seen_interactions.add(interaction)
return “\n”.join(dsl_lines)
def post_to_websequencediagrams(dsl_text, output_image_path):
“””
WebSequenceDiagrams API に DSL を送信し、PNG画像を生成して保存する
“””
payload = {
“message”: dsl_text,
“style”: “default”,
“apiVersion”: “1”
}
try:
response = requests.post(API_URL, data=payload)
response.raise_for_status()
data = response.json()
if data.get(“success”):
img_url = “https://www.websequencediagrams.com/” + data.get(“img”)
img_data = requests.get(img_url).content
with open(output_image_path, ‘wb’) as img_file:
img_file.write(img_data)
print(f”[SUCCESS] Sequence diagram generated: {output_image_path}”)
else:
print(f”[ERROR] API failed to generate diagram: {data}”)
except Exception as e:
print(f”[EXCEPTION] Failed to communicate with WebSequenceDiagrams: {e}”)
def monitor_traces():
print(f”Monitoring Xdebug traces in {TRACE_DIR}…”)
os.makedirs(OUTPUT_DIR, exist_ok=True)
processed_files = set()
while True:
trace_files = glob.glob(os.path.join(TRACE_DIR, “trace..xt”))
for filepath in trace_files:
if filepath not in processed_files:
print(f”Processing new trace file: {filepath}”)
calls = parse_xdebug_trace(filepath)
if calls:
dsl = generate_dsl(calls)
output_img = os.path.join(OUTPUT_DIR, os.path.basename(filepath) + “.png”)
post_to_websequencediagrams(dsl, output_img)
processed_files.add(filepath)
time.sleep(2)
if __name__ == “__main__”:
monitor_traces()
—
4. CI/CDパイプラインへの統合：リグレッションテストと仕様書の自動同期
このワークフローの真価は、ローカル開発環境での利用に留まらず、「CI/CDパイプラインに組み込むことで、E2Eテストや結合テストの実行と同時に、最新の処理フロー図を自動生成し、ドキュメントリポジトリを常時更新し続けること」にある。
レガシーシステムの最大のリスクは「誰も全体像を把握していないため、改修が怖くてできない」という心理的障壁である。CIで自動図解化を行うことで、コードの変更がシステム全体の構造に与えた影響を視覚的に差分として検知できる。
GitHub Actionsワークフロー設定 (`.github/workflows/generate-sequence.yml`)
name: Auto-Generate Sequence Diagrams
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
# 1. テストスイートを実行し、Xdebugトレースを強制収集するジョブ
trace-execution:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Setup PHP with Xdebug
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.2’
extensions: xdebug
ini-values: “xdebug.mode=trace, xdebug.output_dir=${{ github.workspace }}/traces”
- name: Install Composer Dependencies
run: composer install –prefer-dist –no-progress
- name: Run Integration Tests with Trace Trigger
env:
# アプリケーション側でトレースを有効化するトリガーヘッダーや環境変数
XDEBUG_TRIGGER: “1”
run: |
mkdir -p ${{ github.workspace }}/traces
# テストエントリーポイントを実行（例: PHPUnitによる結合テスト）
vendor/bin/phpunit –filter=LegacyOrderProcessTest
- name: Upload Trace Artifacts
uses: actions/upload-artifact@v3
with:
name: xdebug-traces
path: ${{ github.workspace }}/traces/.xt
# 2. 収集されたトレースからシーケンス図を生成し、ドキュメントブランチへコミットするジョブ
generate-diagrams:
needs: trace-execution
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v3
- name: Download Trace Artifacts
uses: actions/download-artifact@v3
with:
name: xdebug-traces
path: ${{ github.workspace }}/traces
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: ‘3.10’
- name: Install Python Dependencies
run: |
pip install requests
- name: Run Conversion Script
env:
TRACE_DIR: “${{ github.workspace }}/traces”
OUTPUT_DIR: “${{ github.workspace }}/docs/sequences”
run: |
python3 .github/scripts/ci_convert.py
- name: Commit and Push Updated Sequence Diagrams
run: |
git config –global user.name “DevOps Architecture Bot”
git config –global user.email “bot@devops.internal”
git add docs/sequences/.png
git diff –quiet && git diff –staged –quiet || (git commit -m “chore: auto-update architecture sequence diagrams [skip ci]” && git push)
—
5. エキスパートのためのトラブルシューティングとアーキテクチャの極み
実運用において遭遇しうるマニアックな問題とその処方箋を記す。
トラブルシューティング 1: 大規模ループによるトレースの爆発とAPI制限
数万回に及ぶデータベースのフェッチや配列のループ処理が含まれるコードをトレースすると、生成されるDSLの行数がWebSequenceDiagramsのAPI制限（文字数オーバー）に抵触し、図が生成されない。
アーキテクトの処方箋:
変換スクリプトの段階で「同一の呼び出しが連続している場合（例: `Repository->find()` が100回連続するなど）」を検知し、DSL上で `[Loop 100 times]` のようなマクロ表記に圧縮するプレフィックスフィルターを実装せよ。これにより、APIのペイロードサイズを劇的に削減しつつ、本質的なコール構造のみを美しく描画できる。
トラブルシューティング 2: 非同期リクエスト（AJAX / イベント駆動）のトレース分断
SPAやキューワーカー（Laravel Queue / Symfony Messenger）を多用するモダン・レガシーハイブリッドな環境では、単一のリクエストスコープを超えてトレースが分断される。
アーキテクトの処方箋:
HTTPリクエストヘッダー（`X-Xdebug-Trace-ID`）をワーカーのペイロードやジョブのプロパティに伝播させ、`xdebug_get_trace_file_name()` をカスタムロガー経由でラップ。ジョブのディスパッチ元とコンシューマ側でトレースファイルをマージする独自のセッション相関レイヤをPHPのブートストラップ層にインジェクトすることで、非同期処理をまたいだ完全なシーケンス図を描出することが可能となる。
—
結言
デバッグとは、単に「バグを修正する作業」ではない。それは「ブラックボックス化された複雑系を、人間の認知限界内に引き戻すための解剖学」である。
Xdebugの生ログをWebSequenceDiagramsへ流し込むパイプラインの構築は、レガシーコードに対する最大の敬意であり、かつ開発組織の認知負荷（Cognitive Load）を劇的にゼロへ近づけるための最も投資対効果の高いDevOpsプラクティスの一つである。今日からこの仕組みを導入し、ドキュメントの神話から解放された真のエンジニアリングを手に入れてほしい。