detach コマンド

概要

detach コマンドは、ターゲットプロセスから Peeka Agent をデタッチし、すべての診断活動を停止し、ターゲットプロセスを元の状態に復元するために使用されます。このコマンドは注入されたすべてのオブザベーションロジックをクリーンアップし、Agent サービスをシャットダウンし、一時ファイルを削除して、ターゲットプロセスに影響がないことを保証します。

使用場面

診断の完了: 診断作業が完了した後にクリーンに終了
リソース占有の回避: Agent が占有しているメモリとファイルディスクリプタを解放
元の状態への復元: すべての関数拡張とオブザベーションロジックを削除
ターゲットプロセスの切り替え: 現在のプロセスからデタッチして、別のプロセスにアタッチする準備をする

コマンドフォーマット

peeka-cli attach <pid>    # まずターゲットプロセスにアタッチ
# ... 診断コマンドを実行 ...
peeka-cli detach          # 完了したらデタッチ

注意: detach コマンドにはパラメータがありません。

デタッチプロセス

detach コマンドは以下のクリーンアップ操作を実行します：

すべてのアクティブなオブザベーションを停止:
- すべての watch オブザベーションを停止
- すべての trace トレースを停止
- すべての stack キャプチャを停止
- すべての monitor モニタリングを停止
- top パフォーマンスプロファイリングを停止
拡張された関数を復元:
- injector.uninject_all() を呼び出してすべてのデコレータを削除
- 関数を元の状態に復元（__peeka_original__ ラッパーを削除）
オブザベーションデータをクリーンアップ:
- オブザベーションバッファをクリア
- すべての watch ID を登録解除
Agent サービスをシャットダウン:
- Unix ドメインソケットをクローズ
- Agent リスニングスレッドを停止
- ソケットファイル (/tmp/peeka_<pid>.sock) を削除
リソースを解放:
- メモリバッファをクリーンアップ
- ファイルディスクリプタをクローズ
- バックグラウンドスレッドを停止

基本的な使い方

1. 通常のデタッチ

# まずターゲットプロセスにアタッチ
peeka-cli attach 12345

# 診断コマンドを実行
peeka-cli watch "mymodule.func" -n 10
peeka-cli monitor "mymodule.func" --interval 1 -c 5

# 完了したらデタッチ
peeka-cli detach

出力例:

{
  "type": "success",
  "command": "detach",
  "data": {
    "pid": 12345,
    "message": "Detached from process 12345"
  }
}

2. デタッチの失敗

デタッチプロセス中にエラーが発生した場合：

{
  "type": "error",
  "command": "detach",
  "error": "Failed to restore function: mymodule.func"
}

処理:

エラーが重要でない場合（例：1つの関数の復元が失敗）、Agent は他のリソースのクリーンアップを続けます
エラーが重要な場合（例：ソケットクローズが失敗）、ターゲットプロセスを再起動することが推奨されます

TUI での使用法

TUI モードの場合：

TUI を起動：
```
peeka  # or python -m peeka.tui
```
ターゲットプロセスに接続した後、1 キーを押して Dashboard ビューに戻ります
Dashboard でコマンドを入力：
```
detach
```
または直接 q キーを押して TUI を終了（自動的に detach が実行されます）

注意点

自動クリーンアップ:
- 異常終了した場合、Peeka Agent は最善を尽くしてクリーンアップを試みます
- ただし 100% の復元は保証されていません。正常終了には detach コマンドを使用することが推奨されます
関数の復元:
- ほとんどの場合、関数は完全に元の状態に復元されます
- まれに、他のコードが同時に関数を変更している場合、完全な復元ができない可能性があります
オブザベーションデータの損失:
- detach 後、消費されていないすべてのオブザベーションデータはクリアされます
- データを保存する必要がある場合は、detach の前にすべてのデータが保存されていることを確認してください
ソケットファイルのクリーンアップ:
- ソケットファイル (/tmp/peeka_<pid>.sock) は自動的に削除されます
- プロセスが異常終了した場合、手動でクリーンアップが必要になることがあります
パフォーマンスの回復:
- detach 後、ターゲットプロセスのパフォーマンスはすぐに元のレベルに回復するはずです
- パフォーマンスの問題が持続する場合、それはターゲットプロセス自体の問題である可能性があります
再アタッチ:
- detach 後、再度同じプロセスに attach できます
- 各 attach は新しいソケットファイルと Agent インスタンスを作成します
プロセスの終了:
- detach の前にターゲットプロセスが終了した場合、Agent は自動的にクリーンアップされます
- 手動で detach を実行する必要はありません

attach コマンドとの関係

attach と detach はペアの操作です：

# ライフサイクル
peeka-cli attach <pid>    # Agent を注入してサービスを開始
# ... 診断操作 ...
peeka-cli detach          # Agent をクリーンアップして元の状態に復元

リソース使用比較:

状態	ソケットファイル	メモリ使用量	関数拡張	バックグラウンドスレッド
attach 前	なし	0	なし	0
attach 後	存在	~10MB	コマンドに依存	1-5
detach 後	なし	0	なし	0

トラブルシューティング

1. detach コマンドが応答しない

# Agent を強制終了（推奨されない）
kill -9 <pid_of_agent_thread>

2. ソケットファイルがクリーンアップされない

# 手動でソケットファイルを削除
rm /tmp/peeka_<pid>.sock

3. 関数が復元されない

detach 後に関数の動作が異常な場合：

他の診断ツールが同時にアタッチされていないか確認
ターゲットプロセスを再起動
Peeka バージョンがターゲットの Python バージョンと互換性があるか確認

4. メモリが解放されない

detach 後にターゲットプロセスのメモリが減少しない場合：

これは Python メモリ管理の通常の動作である可能性があります
Python インタープリタはメモリをすぐに OS に解放しません
手動でガベージコレクションをトリガできます：peeka-cli memory --action gc（detach の前）

権限要件

detach コマンドには以下が必要です：

ターゲットプロセスに正常に attach されていること
ターゲットプロセスとの接続が維持されていること（ソケットが利用可能）

クリーンアップ操作はターゲットプロセス内で実行されるため、追加の権限は必要ありません。