Peeka
かくれんぼ — 名前は子供のゲーム「ピークアブー」から来ています。隠れたバグを見つける診断ツールは、かくれんぼで誰かが見つかったときの驚きの瞬間のようなものです。
PEP 768 (Python 3.14 リモートデバッグプロトコル) ベースのランタイム診断ツールで、非侵入型の関数オブザベーション機能を提供します。
このドキュメントは Peeka v0.1.10 に対応しています。
🌐 言語 / Language: このドキュメントは中文（中国語）、English（英語）、Español（スペイン語）でも利用可能です。
Peeka とは？
Peeka は、本番環境で Python 開発者にリアルタイム診断機能を提供するツールです。ターゲットコードを変更することなく、実行中の Python アプリケーションを動的にオブザーベーションし診断することができます。
なぜ Peeka が必要なの？
従来の Python デバッグ方法は、本番環境で多くの課題に直面します：
- サービスを停止できない - ブレークポイントデバッグはプロセスをブロックする
- 断続的な問題 - 実際の負荷の下でオブザベーションする必要がある
- コード変更の難しさ - 本番環境に自由にデプロイできない
Peeka は特にこれらの本番環境診断課題を解決するために設計されました。
コア機能
🔍 非侵入型オブザベーション
- ターゲットコードを変更する必要なし
- 実行時に動的にオブザベーションロジックをインジェクト
- 診断後に完全に復元可能
⚡ リアルタイム診断
- ミリ秒レベルのデータ送信レイテンシ
- ストリーミングオブザベーションデータプッシュ
- JSON フォーマット出力で他のツールとの連携が容易
🛡️ 本番環境対応
- パフォーマンスオーバーヘッド < 5%
- 完全な例外キャプチャと回復メカニズム
- 固定メモリバッファでメモリ膨張を防止
🎯 条件付きフィルタリング
- 安全な式フィルタリング (simpleeval ベース)
- 柔軟なフィルタリング構文 (パラメータ、戻り値、実行時間など)
- すべてのコードインジェクション攻撃をブロック (
__import__、eval、execなど)
クイックスタート
インストール
pip install peeka
基本的な使い方
1. ターゲットプロセスにアタッチ
peeka-cli attach <pid>
2. 関数呼び出しをオブザーブ
# 5 回の呼び出しをオブザーブ
peeka-cli watch "module.Class.method" --times 5
# 条件付きフィルタリング
peeka-cli watch "module.Class.method" --condition "len(params) > 2"
# リアルタイムストリーミングオブザベーション
peeka-cli watch "module.Class.method"
3. データ処理
# jq で結果を抽出
peeka-cli watch "module.func" | jq 'select(.type == "observation") | .data.result'
# 遅い呼び出しをフィルタ
peeka-cli watch "module.func" | jq 'select(.type == "observation" and .data.duration_ms > 1)'
主な機能
| コマンド | 機能 | ステータス |
|---|---|---|
attach |
ターゲットプロセスにアタッチ | ✅ |
watch |
関数呼び出しをオブザーブ（パラメータ、戻り値、時間） | ✅ |
trace |
呼び出しチェーンと実行時間をトレース | ✅ |
stack |
呼び出しスタックをトレース | ✅ |
monitor |
パフォーマンス統計をモニタリング | ✅ |
logger |
動的にログレベルを調整 | ✅ |
memory |
メモリ分析 | ✅ |
inspect |
実行時オブジェクト検査 | ✅ |
sc/sm |
クラスとメソッドを検索 | ✅ |
reset |
拡張をリセット | ✅ |
thread |
スレッド分析 | ✅ |
top |
関数レベルパフォーマンスサンプリング | ✅ |
detach |
診断セッションを安全に終了 | ✅ |
🎨 インタラクティブ TUI インターフェース
CLI コマンドに加えて、Peeka は機能豊富な TUI（テキストユーザーインターフェース）も提供しています：
- プロセスセレクター - システムプロセスリストを自動表示、検索フィルタリング付き
- 10 個の専用ビュー - ダッシュボード、ウォッチ、トレース、スタック、モニター、ロガー、メモリー、インスペクト、スレッド、トップ
- リアルタイムデータストリーム - オブザベーションデータをストリーミング、一時停止/再開/クリア対応
- オートコンプリート - ターゲットプロセスからクラスとメソッドを動的に取得
- テーマサポート - 複数のビルトインカラーテーマ
# TUI を起動
peeka
# 数字キーでビューを切り替え
# 1/2/3/4/5/6/7/8/9/0
技術的ハイライト
Python 3.14 リモートデバッグプロトコル (PEP 768)
コアの sys.remote_exec(pid, script_path) 関数がシステム全体の動作の鍵であり、複雑なプロセスアタッチ、コードインジェクション、実行スケジューリングロジックをカプセル化しています。
Python < 3.14 へのフォールバック: 古い Python バージョンでは、Linux では GDB + ptrace、macOS では LLDB + dlopen を使用 (参考: pyrasite)。
Unix ドメインソケット
Unix ドメインソケットをプロセス間通信の主なメカニズムとして使用：
- より高い送信効率 - ネットワークプロトコルスタックが不要
- より強いセキュリティ - ローカルプロセスのみが利用可能
- シンプルで信頼性 - 長さプレフィックス + JSON フォーマット
安全な条件式評価
simpleeval ライブラリベースで安全な条件付きフィルタリングを実装：
- AST ホワイトリスト - 安全な操作のみを許可
- 属性保護 - リフレクション攻撃をブロック
- 関数ブラックリスト - 危険な関数を無効化
サポートされている Python バージョン
| Python バージョン | アタッチメカニズム | 要件 |
|---|---|---|
| 3.14+ | PEP 768 sys.remote_exec |
なし |
| 3.8.1-3.13 | Linux: GDB + ptrace、macOS: LLDB + dlopen | Linux: GDB 7.3+, python3-dbg, CAP_SYS_PTRACE、macOS: Xcode Command Line Tools |
ライセンス
Peeka は Apache License 2.0 の下でオープンソースです。
謝辞
- セキュリティ評価: simpleeval
- リモートデバッグプロトコル: PEP 768