calltrace-rs 1.1.4

# Phase 1: アーキテクチャ設計・基礎実装 詳細計画

## 期間
Week 1-2 (14日間)

## 目標
LD_PRELOAD機能を利用した基本的な関数呼び出しトレース機能の実装と、最小限のJSON出力機能を完成させる。

## 詳細タスク分解

### Week 1: Days 1-7

#### Day 1: プロジェクト基盤整備
**担当**: 全員
**所要時間**: 8時間

- [x] プロジェクト構造の確定
- [x] CMakeビルドシステム設定
- [x] 基本ヘッダーファイル作成 (`calltrace.h`, `internal.h`)
- [ ] 開発環境セットアップスクリプト作成
- [ ] Git pre-commit hook設定
- [ ] コーディング規約ドキュメント作成

**成果物**:
- 完全なプロジェクト構造
- ビルド可能なCMake設定
- 開発者向けセットアップガイド

**検証方法**:
```bash
./scripts/build.sh -t Debug
# エラーなしでビルドシステムが動作することを確認
```

#### Day 2-3: Core Library基盤実装
**担当**: Core開発者
**所要時間**: 16時間

**実装対象**:
1. **`src/core/calltrace.c`** - メインAPI
   ```c
   calltrace_error_t calltrace_init(const calltrace_config_t* config);
   calltrace_error_t calltrace_cleanup(void);
   calltrace_error_t calltrace_start(void);
   calltrace_error_t calltrace_stop(void);
   ```

2. **`src/core/state.c`** - グローバル状態管理
   ```c
   calltrace_state_t g_calltrace_state;
   calltrace_error_t state_init(void);
   calltrace_error_t state_cleanup(void);
   ```

3. **`src/utils/timestamp.c`** - タイムスタンプ機能
   ```c
   uint64_t calltrace_get_timestamp(void);
   const char* calltrace_format_timestamp(uint64_t timestamp);
   ```

**実装手順**:
1. グローバル状態構造体の定義と初期化
2. 基本的なエラーハンドリング機構
3. 設定システムの基本実装
4. タイムスタンプ取得機能

**テスト計画**:
- ユニットテスト: 各関数の正常系・異常系
- 初期化/終了処理の検証
- メモリリーク検査

#### Day 4-5: LD_PRELOAD Hook機構実装
**担当**: システム開発者
**所要時間**: 16時間

**実装対象**:
1. **`src/core/hooks.c`** - フック機構
   ```c
   __attribute__((constructor)) void calltrace_init_hooks(void);
   __attribute__((destructor)) void calltrace_cleanup_hooks(void);
   void calltrace_function_entry(const char* func_name, void* func_addr);
   void calltrace_function_exit(const char* func_name, void* func_addr, void* return_val);
   ```

2. **動的シンボル解決**
   ```c
   void* resolve_original_function(const char* symbol_name);
   bool install_function_hook(const char* func_name, void* hook_func);
   ```

**実装手順**:
1. LD_PRELOAD環境での初期化処理
2. dlsym()を使った動的シンボル解決
3. 基本的な関数フック機構（main関数対象）
4. 関数エントリー/エグジット検知

**検証方法**:
```bash
# テストプログラム作成
echo 'int main() { return 0; }' > test.c
gcc -o test test.c

# フック動作確認
LD_PRELOAD=./libcalltrace.so ./test
# main関数の呼び出しが検知されることを確認
```

#### Day 6-7: シンボル解決機能実装
**担当**: システム開発者
**所要時間**: 16時間

**実装対象**:
1. **`src/utils/symbols.c`** - シンボル解決
   ```c
   const char* calltrace_resolve_symbol(void* addr);
   const char* calltrace_get_library_name(void* addr);
   bool calltrace_is_system_function(const char* func_name);
   ```

2. **シンボルキャッシュ機構**
   ```c
   typedef struct symbol_cache_entry {
       void* address;
       char* symbol_name;
       char* library_name;
       struct symbol_cache_entry* next;
   } symbol_cache_entry_t;
   ```

**実装手順**:
1. dladdr()を使ったアドレス→シンボル名解決
2. ライブラリ名取得機能
3. パフォーマンス向上のためのキャッシュ機構
4. システム関数の識別機能

**パフォーマンス要件**:
- シンボル解決時間: 1ms以内（キャッシュヒット時）
- キャッシュヒット率: 90%以上
- メモリ使用量: 最大10MB

### Week 2: Days 8-14

#### Day 8-9: スレッド管理機能実装
**担当**: 並行処理専門者
**所要時間**: 16時間

**実装対象**:
1. **`src/utils/threads.c`** - スレッド管理
   ```c
   thread_context_t* calltrace_get_thread_context(void);
   calltrace_error_t calltrace_cleanup_thread_context(pthread_t thread_id);
   ```

2. **スレッドローカルストレージ**
   ```c
   __thread int tls_context_index = -1;
   static thread_context_t thread_table[MAX_THREADS];
   ```

**実装手順**:
1. スレッド固有データ管理システム
2. TLS（Thread Local Storage）活用
3. スレッド生成/終了時の自動管理
4. マルチスレッド環境での競合状態対策

**検証方法**:
```c
// マルチスレッドテストプログラム
#include <pthread.h>
void* thread_func(void* arg) {
    // CallTraceが各スレッドを正しく識別できることを確認
    return NULL;
}
```

#### Day 10-11: 基本JSON出力エンジン実装
**担当**: 出力システム開発者
**所要時間**: 16時間

**実装対象**:
1. **`src/core/json_output.c`** - JSON出力
   ```c
   calltrace_error_t calltrace_json_write_header(FILE* stream);
   calltrace_error_t calltrace_json_write_call(FILE* stream, const calltrace_call_info_t* call_info);
   calltrace_error_t calltrace_json_write_footer(FILE* stream);
   ```

2. **JSON構造設計**
   ```json
   {
     "trace_session": {
       "start_time": "2025-08-15T10:30:00.000Z",
       "process_info": {
         "pid": 12345,
         "executable": "/path/to/program"
       },
       "calls": [
         {
           "function": "main",
           "address": "0x401000",
           "timestamp": 1692097800001,
           "thread_id": 140234567890
         }
       ]
     }
   }
   ```

**実装手順**:
1. 基本的なJSON構造出力
2. 文字列エスケープ処理
3. インデントとフォーマット
4. ストリーミング出力対応

**品質要件**:
- RFC 7159準拠のJSON出力
- 大きなファイルでもメモリ効率的な出力
- 不正な文字列の適切なエスケープ

#### Day 12-13: 基本フィルタリング機能実装
**担当**: フィルタエンジン開発者
**所要時間**: 16時間

**実装対象**:
1. **`src/utils/filters.c`** - フィルタエンジン
   ```c
   bool calltrace_should_trace(const char* func_name);
   calltrace_error_t calltrace_add_filter(const char* pattern);
   calltrace_error_t calltrace_load_filters_from_file(const char* filename);
   ```

2. **フィルタ機能**
   - ワイルドカードパターンマッチング (`malloc*`, `pthread_*`)
   - 除外リスト (`!__*`, `!_dl_*`)
   - 包含リスト (`main`, `user_*`)

**実装手順**:
1. 基本的なワイルドカードマッチング
2. 包含/除外ルールの実装
3. 設定ファイルからのフィルタ読み込み
4. 動的フィルタ更新機能

**テスト計画**:
```bash
# フィルタテストケース
calltrace_add_filter("main");          # main関数のみトレース
calltrace_add_filter("!__*");          # __で始まる関数を除外
calltrace_add_filter("pthread_*");     # pthread_で始まる関数をトレース
```

#### Day 14: 統合テストと検証
**担当**: 全員
**所要時間**: 8時間

**統合テスト項目**:

1. **基本機能テスト**
   ```bash
   # 単純なプログラムのトレース
   echo 'int main() { printf("Hello\n"); return 0; }' > test.c
   gcc -o test test.c
   LD_PRELOAD=./libcalltrace.so ./test
   ```

2. **JSON出力検証**
   ```bash
   # 有効なJSONが出力されることを確認
   LD_PRELOAD=./libcalltrace.so ./test | jq '.'
   ```

3. **マルチスレッドテスト**
   ```c
   // pthread使用プログラムでの動作確認
   #include <pthread.h>
   void* worker(void* arg) { return NULL; }
   int main() {
       pthread_t thread;
       pthread_create(&thread, NULL, worker, NULL);
       pthread_join(thread, NULL);
       return 0;
   }
   ```

4. **フィルタテスト**
   ```bash
   # 特定の関数のみがトレースされることを確認
   export CALLTRACE_FILTER="main,printf"
   LD_PRELOAD=./libcalltrace.so ./test
   ```

**成果物検証**:
- [ ] LD_PRELOADによる基本的な関数フック動作
- [ ] JSON形式での呼び出し履歴出力
- [ ] マルチスレッド環境での正常動作
- [ ] 基本的なフィルタリング機能
- [ ] メモリリークなし（Valgrind検証）

## 進捗管理

### Daily Standup Topics
1. 昨日の完了タスク
2. 今日の予定タスク
3. ブロッカーや課題
4. 他チームメンバーへの依存関係

### Weekly Review Points
- **Week 1終了時**:
  - 基本フック機構の動作確認
  - シンボル解決機能のパフォーマンス測定
  - 技術的リスクの再評価

- **Week 2終了時**:
  - 全機能の統合テスト結果
  - パフォーマンス要件の達成確認
  - Phase 2への準備状況確認

## リスク管理

### 高リスク項目
1. **LD_PRELOAD環境での安定性**
   - 対策: 段階的テスト、各種環境での検証
   - 検出方法: 継続的な統合テスト

2. **マルチスレッド競合状態**
   - 対策: スレッドセーフ設計、詳細なテスト
   - 検出方法: Thread Sanitizer使用

3. **パフォーマンスオーバーヘッド**
   - 対策: プロファイリング、最適化
   - 検出方法: ベンチマーク継続実行

### 中リスク項目
1. **メモリリーク**
   - 対策: RAII原則適用、Valgrind検証
   - 検出方法: 自動メモリチェック

2. **JSON出力の正確性**
   - 対策: JSON検証ツール使用
   - 検出方法: 自動JSON検証テスト

## 品質基準

### コード品質
- [ ] 静的解析（cppcheck）エラーなし
- [ ] すべての関数にユニットテスト
- [ ] テストカバレッジ80%以上
- [ ] メモリリーク検出なし

### 機能品質
- [ ] 基本的なプログラムのトレースが正常動作
- [ ] JSON出力がRFC 7159準拠
- [ ] マルチスレッドプログラムで競合状態なし
- [ ] フィルタ機能が期待通り動作

### パフォーマンス品質
- [ ] ベースライン比5%以内のオーバーヘッド
- [ ] シンボル解決1ms以内（キャッシュヒット時）
- [ ] メモリ使用量100MB以内

## Next Phase準備

Phase 2移行条件:
1. すべての基本機能が動作
2. 品質基準をクリア
3. パフォーマンス要件を満たす
4. 技術的負債が許容範囲内

Phase 2で必要な準備:
- より高度なJSON構造設計
- パフォーマンス最適化計画
- 拡張機能仕様の詳細化