TUI 使用ガイド

目次

1. 概要
2. TUI の起動
   1. 方法 1: 直接起動
   2. 方法 2: Python モジュールとして起動
   3. 起動オプション
3. TUI 画面レイアウト
   1. 領域の説明
4. グローバルショートカット
5. 10 のビュー詳説
   1. 1. Dashboard ビュー（1 キー）
   2. 2. Watch ビュー（2 キー）
   3. 3. Trace ビュー（3 キー）
   4. 4. Stack ビュー（4 キー）
   5. 5. Monitor ビュー（5 キー）
   6. 6. Memory ビュー（6 キー）
   7. 7. Logger ビュー（7 キー）
   8. 8. Inspect ビュー（8 キー）
   9. 9. Threads ビュー（9 キー）
   10. 10. Top ビュー（0 キー）
6. TUI 特有の機能
   1. 1. オートコンプリート
   2. 2. リアルタイムストリーミングデータ
   3. 3. インタラクティブツリー構造
   4. 4. カラーコーディング
   5. 5. 専用クライアント
   6. 6. 自動スクロール
7. TUI vs CLI 比較
8. 使用テクニック
   1. 1. ビューを素早く切り替え
   2. 2. 複数ビューを組み合わせて使用
   3. 3. コマンド履歴を使用
   4. 4. 出力を素早くコピー
   5. 5. テーマカスタマイズ
9. トラブルシューティング
   1. 1. TUI 起動失敗
   2. 2. ターミナル表示が異常
   3. 3. ショートカットの競合
   4. 4. パフォーマンスの問題
   5. 5. 接続の喪失
10. 権限要件
11. まとめ

概要

Peeka は Textual フレームワークをベースに、機能豊富なテキストユーザーインターフェース（TUI） を提供しています。TUI モードは CLI よりも直感的なインタラクティブ体験を提供し、リアルタイムデータストリーミング、インタラクティブ操作、カラー出力、ショートカットナビゲーションをサポートしています。

主な用途:

• インタラクティブ診断: コマンドを頻繁に切り替えてリアルタイムデータを確認する必要がある場合
• リアルタイムモニタリング: パフォーマンス指標、ログ出力、メモリ変化を観察する場合
• 可視化分析: ツリー構造で呼び出しチェーンを表示し、色分けされたパフォーマンスデータを分析する場合
• 探索的デバッグ: 使用するコマンドが不明で、TUI で段階的に探索する場合

TUI の起動

方法 1: 直接起動

peeka

方法 2: Python モジュールとして起動

python -m peeka.tui

起動オプション

# カスタムテーマを使用
peeka --theme dracula

# 使用可能なテーマを一覧表示
peeka --list-themes

使用可能なテーマ:

• default - Textual デフォルトテーマ
• nord - Nord 配色
• dracula - Dracula 配色
• gruvbox - Gruvbox 配色
• monokai - Monokai 配色
• solarized-light - Solarized Light
• solarized-dark - Solarized Dark

TUI 画面レイアウト

TUI を起動すると、画面は以下の領域に分かれています：

領域の説明

• Header: TUI タイトルと現在時刻を表示
• PID Status: 現在アタッチされているターゲットプロセスの PID を表示
• Tab Bar: 使用可能なすべてのビューのタブを表示
• View Content: 現在アクティブなビューのコンテンツ領域
• Footer: グローバルショートカットのヒントを表示

グローバルショートカット

ショートカット	機能	説明
1	Dashboard ビュー	ダッシュボードに切り替え
2	Watch ビュー	関数オブザベーションに切り替え
3	Trace ビュー	呼び出しチェーントレースに切り替え
4	Stack ビュー	呼び出しスタックキャプチャに切り替え
5	Monitor ビュー	パフォーマンスモニタリングに切り替え
6	Memory ビュー	メモリ分析に切り替え
7	Logger ビュー	ログ管理に切り替え
8	Inspect ビュー	オブジェクト検査に切り替え
9	Threads ビュー	スレッド管理に切り替え
0	Top ビュー	パフォーマンスアナライザに切り替え
?	Help ヘルプ	ヘルプ情報を表示（一部のビューで使用可能）
escape / q	前の画面に戻る / 終了	Dashboard では終了、その他のビューでは Dashboard に戻る

10 のビュー詳説

1. Dashboard ビュー（1 キー）

機能: ターゲットプロセスのリアルタイム診断概要

特徴:

• スレッド数と状態のサマリー
• daemon マーカーと現在のトップフレームを含むスレッド一覧
• メモリ、GC、ランタイム情報の概要
• クライアントと Agent のイベントをリアルタイム表示する Activity Log
• 現在のプロセススナップショットのリフレッシュをサポート

使い方:

1. TUI を起動してターゲットプロセスにアタッチ
2. スレッド、メモリ、GC、ランタイム状態を確認
3. Activity Log で接続状態とコマンド実行状態を確認
4. 他のビューのショートカットを押して専用ビューに切り替え

適した場面: プロセスの健全性、スレッド状態、診断セッションの接続状況を素早く確認する場合

---

2. Watch ビュー（2 キー）

機能: 関数呼び出しの引数、戻り値、例外、実行時間をオブザーブ

特徴:

• リアルタイムストリーミング更新（オブザベーションデータを継続表示）
• 条件フィルタリングをサポート
• オブザベーションポイント制御（-b / -e / -s / -f）
• カラー出力（成功=緑、例外=赤）
• 呼び出し回数、累積実行時間を表示

インタラクティブ操作:

• 関数パターンを入力（例: module.Class.method）
• オブザベーション回数を設定（-n パラメータ）
• 条件式を設定（–condition）
• Enter を押してオブザベーション開始
• Delete を押してオブザベーション停止

出力フォーマット:

• テーブルビュー: 主要フィールドを表示（params, returnObj, cost, success）
• 詳細ビュー: JSON フォーマットで完全なデータを表示

---

3. Trace ビュー（3 キー）

機能: 関数呼び出しチェーンをトレースし、メソッド呼び出しの階層関係と実行時間を表示

特徴:

• ツリー構造表示: 呼び出し階層を可視化
• 実行時間の色分け:
  • 緑：< 10ms
  • 黄：10-100ms
  • 赤：≥ 100ms
• リアルタイムストリーミング更新: 呼び出しのたびに即座に表示
• 展開/折りたたみをサポート: インタラクティブなツリーノード
• 深度制限: トレースする階層数を制御（-d パラメータ）

インタラクティブ操作:

• 関数パターンを入力
• トレース深度を設定（デフォルト 3 階層）
• ビルトイン関数をスキップする設定（–skip-builtin）
• Enter を押してトレース開始
• Delete を押してトレース停止
• ノードをクリックして展開/折りたたみ（マウスサポート）

出力例: Trace ビューでは、呼び出しチェーンと各ノードの実行時間を展開可能なツリーとして表示します。

---

4. Stack ビュー（4 キー）

機能: 関数が呼び出されたときの完全な呼び出しスタックをキャプチャ

特徴:

• エントリポイントから現在の関数までの完全な呼び出しチェーンを表示
• 条件フィルタリングをサポート
• リアルタイムストリーミング更新
• ファイルパス、行番号、関数名を表示

インタラクティブ操作:

• 関数パターンを入力
• スタック深度を設定（–depth パラメータ）
• 条件式を設定
• Enter を押してキャプチャ開始
• Delete を押してキャプチャ停止

出力フォーマット:

• 呼び出しのたびにスタックスナップショットを 1 つ表示
• 呼び出しエントリからターゲット関数までの完全なパスを表示

---

5. Monitor ビュー（5 キー）

機能: 定期的に関数のパフォーマンス統計を出力（呼び出し回数、成功率、応答時間）

特徴:

• 周期的な更新（間隔を設定可能）
• 集計された統計を表示：
  • 総呼び出し回数
  • 成功回数 / 失敗回数
  • 平均実行時間 / 最小実行時間 / 最大実行時間
• 複数の関数を同時にモニタリング可能
• リアルタイムグラフ表示（オプション）

インタラクティブ操作:

• 関数パターンを入力
• 更新間隔を設定（–interval パラメータ、単位：秒）
• 周期数を設定（-c パラメータ、-1 は無限）
• Enter を押してモニタリング開始
• Delete を押してモニタリング停止

出力例:

Function: module.func
  Total Calls: 1523
  Success: 1500 (98.5%)
  Failed: 23 (1.5%)
  Avg Time: 12.3ms
  Min Time: 0.5ms
  Max Time: 250.8ms

---

6. Memory ビュー（6 キー）

機能: プロセスのメモリ使用状況とメモリ割り当てを分析

特徴:

• メモリ概要（合計メモリ、RSS、ヒープサイズ）
• Top N メモリ割り当てトラッキング
• ファイル / 行番号ごとにグループ化
• 手動で GC をトリガ可能
• メモリスナップショット比較

インタラクティブ操作:

• メモリ概要を表示（overview 操作）
• メモリトラッキングを開始（start 操作）
• Top N 割り当てを表示（top 操作）
• ガベージコレクションをトリガ（gc 操作）
• メモリトラッキングを停止（stop 操作）

よく使われる操作ショートカット:

• r: データを更新
• g: GC をトリガ
• t: トラッキング状態を切り替え

---

7. Logger ビュー（7 キー）

機能: 実行時に Python logger のログレベルを動的に調整

特徴:

• すべての logger と現在のレベルを一覧表示
• 実行時にログレベルを変更（DEBUG / INFO / WARNING / ERROR）
• ターゲットプロセスを再起動する必要がない
• パターンマッチングをサポート（例: myapp.*）

インタラクティブ操作:

• すべての logger を一覧表示（list 操作）
• 特定の logger のレベルを取得（get 操作）
• logger のレベルを設定（set 操作）
• パターンマッチングをサポート（–pattern）

出力例:

Logger: myapp.database
  Level: INFO
  Effective Level: INFO
  Handler: StreamHandler

Logger: myapp.api
  Level: DEBUG
  Effective Level: DEBUG
  Handler: FileHandler

---

8. Inspect ビュー（8 キー）

機能: 実行時のオブジェクト検査と式評価

特徴:

• Python 式を実行（セーフサンドボックス）
• オブジェクトの属性を検査
• 変数の値を確認
• locals() / globals() 検査をサポート

インタラクティブ操作:

• Python 式を入力（例: len(my_list)）
• オブジェクトパスを入力（例: module.MyClass.attr）
• Enter を押して実行
• JSON フォーマットされた結果を確認

セキュリティ制限:

• eval / exec / __import__ を無効化
• 読み取り専用アクセス（オブジェクトを変更できない）
• simpleeval ベースのセーフサンドボックス

---

9. Threads ビュー（9 キー）

機能: すべてのスレッドを一覧表示し、スレッドの状態とスタックを検査

特徴:

• リアルタイムでスレッドリストを更新
• スレッドの状態を表示（RUNNABLE / WAITING / TIMED_WAITING）
• スレッド ID、名前、daemon フラグを表示
• スレッドをクリックして完全なスタックを表示
• 状態でフィルタリング、フィールドでソートをサポート

インタラクティブ操作:

• すべてのスレッドを表示（list モード）
• スレッドをクリックして詳細を表示（detail モード）
• 状態でフィルタリング（RUNNABLE / WAITING / TIMED_WAITING）
• フィールドでソート（tid / name / state）

出力フォーマット:

• テーブルビュー: スレッドリスト（tid, name, state, stack_depth）
• 詳細ビュー: 完全なスタックフレーム（filename, lineno, funcname, locals_keys）

ショートカット:

• r: スレッドリストを更新
• Enter: 選択したスレッドの詳細を表示
• escape: リストビューに戻る

---

10. Top ビュー（0 キー）

機能: 関数レベルサンプリングパフォーマンスアナライザ（py-spy top と同様）

特徴:

• リアルタイムパフォーマンスランキング
• CPU 使用割合を表示（own / total）
• 関数の実行時間を表示（own_time / total_time）
• サンプリングモードで、パフォーマンスオーバーヘッド < 5%
• 様々なフィールドでソートをサポート
• 色分け（赤=高 CPU、黄=中、緑=低）

インタラクティブ操作:

• サンプリング間隔を設定（–interval パラメータ、デフォルト 10ms）
• 表示周期を設定（–cycles パラメータ）
• ソートフィールドを選択（own / total / own-time / total-time）
• Enter を押して分析開始
• Delete を押して分析停止
• c キーで統計をクリア（reset）

出力例:

Function                     Own%   Total%  Own Time  Total Time
───────────────────────────────────────────────────────────────
compute_matrix              45.3%   58.7%   0.453s    0.587s
multiply                    12.8%   13.4%   0.128s    0.134s
log_result                   8.2%    8.9%   0.082s    0.089s

ショートカット:

• r: データを更新
• s: ソートフィールドを切り替え
• Enter: パフォーマンス分析を開始
• Delete: パフォーマンス分析を停止
• c: 統計データをクリア（reset）

---

TUI 特有の機能

CLI モードと比較して、TUI は以下の特有の機能を提供します：

1. オートコンプリート

Dashboard 入力ボックスはコマンドとパラメータのオートコンプリートをサポート：

• コマンド名補完：wa と入力 → Tab を押す → watch
• パラメータ補完：watch - と入力 → Tab を押す → すべてのパラメータを表示
• パターン補完：watch mymod と入力 → Tab を押す → モジュール内のクラスとメソッドを表示

補完ソース:

• ターゲットプロセスから動的にモジュール、クラス、メソッド情報を取得
• 補完結果をキャッシュして応答速度を向上

2. リアルタイムストリーミングデータ

すべてのオブザベーションコマンド（watch / trace / stack / monitor / top / agent_log）はリアルタイムストリーミング更新をサポート：

• データはオブザベーションフレーム（OBS frame）の形式でプッシュされる
• TUI は自動的に解析して画面を更新
• ストリームの一時停止/再開をサポート（一部のビュー）

3. インタラクティブツリー構造

Trace ビューはインタラクティブツリー構造を提供：

• ノードは展開/折りたたみ可能
• マウスクリックをサポート
• キーボードナビゲーション（↑ / ↓ / Enter / ← / →）

4. カラーコーディング

TUI は色を使ってデータの可読性を向上：

• 成功/失敗: 緑=成功、赤=失敗
• 実行時間の階層: 緑=速い（<10ms）、黄=中（10-100ms）、赤=遅い（>=100ms）
• CPU 使用量: 色の強さで CPU 使用度を表現
• ログレベル: DEBUG=青、INFO=緑、WARNING=黄、ERROR=赤

5. 専用クライアント

各ビューは独立した StreamingAgentClient を使用：

• データの混同を回避
• 並行操作をサポート（複数のビューが同時に動作）
• 自動再接続メカニズム

6. 自動スクロール

Watch / Trace / Stack ビューは自動スクロールをサポート：

• 最新データが常に見える
• 手動で上にスクロールすると自動スクロールを停止
• 一番下まで手動でスクロールすると自動スクロールを再開

---

TUI vs CLI 比較

特性	TUI モード	CLI モード
インタラクティブ体験	リアルタイム、可視化、ショートカットナビゲーション	コマンドライン入力、スクリプト化に適している
データ表示	ツリー構造、テーブル、カラーコーディング	純粋な JSON 出力
リアルタイム更新	自動更新、ストリーミングプッシュ	手動で更新するかコマンドを再実行する必要がある
オートコンプリート	コマンド、パラメータ、パターン補完をサポート	shell 補完プラグインが必要
マルチタスク	複数ビューの並行実行、素早い切り替え	複数のターミナルウィンドウが必要
適した場面	インタラクティブ診断、リアルタイムモニタリング、探索的デバッグ	スクリプト化、自動化、CI/CD 統合
出力フォーマット	フォーマットされたテーブル、ツリー構造、カラーハイライト	JSONL（jq / grep 処理に便利）
学習曲線	中程度（ショートカットに慣れる必要がある）	低い（標準 CLI コマンド）
パフォーマンスオーバーヘッド	やや高い（UI レンダリング）	低い（純粋なデータ転送）

選択の推奨:

• 開発デバッグ: TUI を優先的に使用（インタラクティブ体験が良い）
• 自動化スクリプト: CLI を使用（出力フォーマットが標準化されている）
• CI/CD 統合: CLI を使用（TTY なし環境）
• パフォーマンス分析: どちらでも可（TUI は可視化がより直感的、CLI はデータ出力が便利）

---

使用テクニック

1. ビューを素早く切り替え

数字キーを使ってビュー間を素早く切り替えられます。Dashboard に戻る必要はありません：

2 を押す → Watch ビュー
3 を押す → Trace ビュー
5 を押す → Monitor ビュー
0 を押す → Top ビュー

2. 複数ビューを組み合わせて使用

異なるビューは並行して動作できます（各ビューは独立したクライアントを使用）：

1. Watch ビューでオブザベーションを開始（2 を押してコマンドを入力し Enter）
2. Monitor ビューに切り替えてモニタリングを開始（5 を押してコマンドを入力し Enter）
3. Top ビューに切り替えてパフォーマンス分析を開始（0 を押してコマンドを入力し Enter）
4. 各ビューを切り替えてリアルタイムデータを確認

3. コマンド履歴を使用

Dashboard 入力ボックスはコマンド履歴をサポート：

• ↑: 前のコマンド
• ↓: 次のコマンド
• 履歴はセッション内で永続化される

4. 出力を素早くコピー

TUI の出力は直接クリップボードにコピーできます：

1. マウスでテキストを選択
2. Ctrl+C でコピー（またはターミナルのデフォルトショートカット）
3. 他のツール（エディタ、ドキュメントなど）に貼り付け

5. テーマカスタマイズ

ターミナルの背景に合わせて適切なテーマを選択：

# 明るい背景
peeka --theme solarized-light

# 暗い背景
peeka --theme dracula

# すべてのテーマを一覧表示
peeka --list-themes

---

トラブルシューティング

1. TUI 起動失敗

エラー: ModuleNotFoundError: No module named 'textual'

解決策:

pip install peeka[tui]
# または
pip install textual

2. ターミナル表示が異常

エラー: 文字表示がおかしい、色が失われる

解決策:

• ターミナルが 256 色または 24 ビット真色をサポートしていることを確認
• 環境変数を設定：

  export TERM=xterm-256color
  export COLORTERM=truecolor
  

3. ショートカットの競合

問題: ショートカットがターミナルまたは shell にインターセプトされる

解決策:

• ターミナルのショートカット設定を確認
• q の代わりに escape キーで前のレベルに戻る
• Dashboard で完全なコマンドを入力（ショートカットを使用しない）

4. パフォーマンスの問題

問題: TUI 画面がカクつく、遅延が大きい

解決策:

• サンプリング頻度を下げる（top コマンドで大きな --interval を使用）
• オブザベーション回数を減らす（watch コマンドで -n で回数を制限）
• CLI モードを使用（TUI レンダリングにオーバーヘッドがあるため）

5. 接続の喪失

問題: Connection lost または Socket error

解決策:

• ターゲットプロセスがまだ実行されているか確認
• socket ファイル（/tmp/peeka_<pid>.sock）が存在するか確認
• ターゲットプロセスに再度アタッチ

---

権限要件

TUI モードの権限要件は CLI モードと同じです：

• プロセスアタッチ: CAP_SYS_PTRACE または同じ UID が必要
• ptrace_scope: ptrace_scope <= 1 が必要（Linux）
• Python バージョン:
  • Python 3.14+：PEP 768 sys.remote_exec() を使用
  • Python 3.8.1-3.13：Linux は GDB と python3-dbg、macOS は LLDB（Xcode Command Line Tools）が必要

詳細な権限要件は attach コマンドドキュメント を参照してください。

---

まとめ

Peeka TUI は完全なインタラクティブ診断体験を提供し、頻繁な操作、リアルタイムモニタリング、可視化分析が必要な場面に適しています。10 個の専用ビューとグローバルショートカットにより、開発者は複雑なコマンドパラメータを記憶することなく、効率的に Python アプリケーションの問題を診断できます。

ベストプラクティス:

• 開発環境：TUI を優先的に使用（インタラクティブ体験が良い）
• 本番環境：必要に応じて TUI（モニタリング）または CLI（スクリプト化）を選択
• 自動化シナリオ：CLI を使用（出力が標準化されていて統合が容易）

TUI を使い始めましょう：

peeka

? を押してヘルプを表示し、1/2/3/4/5/6/7/8/9/0 でビューを切り替えて、診断を開始しましょう！