calltrace-rs 1.1.4

# CallTrace - 技術アーキテクチャ設計書

## 1. システム概要

### 1.1 アーキテクチャ概要
CallTraceは、Linux環境でLD_PRELOAD機能を利用した動的関数呼び出しトレースライブラリです。対象プログラムのバイナリ修正なしに、実行時の関数呼び出しパターンを取得し、構造化されたJSON形式で出力します。

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Target App    │────│   libcalltrace   │────│   JSON Output   │
│                 │    │   (LD_PRELOAD)   │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │  Symbol Resolver │
                       │  Thread Manager  │
                       │  Call Stack Mgr  │
                       │  Filter Engine   │
                       └──────────────────┘
```

### 1.2 コンポーネント構成

| コンポーネント | 責務 | 実装場所 |
|---------------|------|----------|
| **Core Library** | メインAPI、状態管理 | `src/core/` |
| **Hook Engine** | 関数フック、LD_PRELOAD処理 | `src/core/hooks.c` |
| **Symbol Resolver** | シンボル解決、アドレス変換 | `src/utils/symbols.c` |
| **Thread Manager** | スレッド固有データ管理 | `src/utils/threads.c` |
| **JSON Engine** | 構造化出力、フォーマット | `src/core/json_output.c` |
| **Filter Engine** | 関数フィルタリング | `src/utils/filters.c` |

## 2. 詳細設計

### 2.1 LD_PRELOAD フック機構

#### シンボル解決アルゴリズム
```c
// メイン解決フロー
void* resolve_symbol(const char* symbol_name) {
    // 1. 現在のプロセスから検索
    void* addr = dlsym(RTLD_NEXT, symbol_name);
    if (addr) return addr;
    
    // 2. デフォルトライブラリから検索
    addr = dlsym(RTLD_DEFAULT, symbol_name);
    if (addr) return addr;
    
    // 3. 明示的ライブラリロード
    return dlopen_and_resolve(symbol_name);
}
```

#### 関数フック戦略
```c
// GNU属性を利用したコンストラクタ/デストラクタ
__attribute__((constructor))
void calltrace_init_hooks(void) {
    // ライブラリロード時に自動実行
    initialize_hook_system();
}

// 実際のフック実装
#define HOOK_FUNCTION(func_name) \
    typeof(&func_name) original_##func_name = NULL; \
    void* hooked_##func_name(...) { \
        calltrace_function_entry(#func_name, __builtin_return_address(0)); \
        void* result = original_##func_name(__VA_ARGS__); \
        calltrace_function_exit(#func_name, __builtin_return_address(0), result); \
        return result; \
    }
```

### 2.2 呼び出しスタック管理

#### スレッドローカルストレージ設計
```c
// TLS変数
__thread thread_context_t* tls_context = NULL;

typedef struct call_node {
    char function_name[MAX_FUNCTION_NAME_LEN];
    uint64_t enter_timestamp;
    uint64_t exit_timestamp;
    size_t depth;
    struct call_node* parent;
    struct call_node* children;
    size_t child_count;
} call_node_t;

typedef struct thread_context {
    pthread_t thread_id;
    call_node_t* root_call;
    call_node_t* current_call;
    size_t max_depth;
    bool tracing_active;
} thread_context_t;
```

#### 呼び出し履歴追跡アルゴリズム
```c
void calltrace_function_entry(const char* func_name, void* func_addr) {
    thread_context_t* ctx = get_thread_context();
    
    // 新しい呼び出しノード作成
    call_node_t* new_call = create_call_node(func_name, func_addr);
    new_call->parent = ctx->current_call;
    new_call->depth = ctx->current_call ? ctx->current_call->depth + 1 : 0;
    
    // 親ノードに子として追加
    if (ctx->current_call) {
        add_child_call(ctx->current_call, new_call);
    } else {
        ctx->root_call = new_call;
    }
    
    ctx->current_call = new_call;
}
```

### 2.3 JSON出力エンジン

#### 入れ子構造JSON設計
```json
{
  "trace_session": {
    "start_time": "2025-08-15T10:30:00.000Z",
    "end_time": "2025-08-15T10:30:05.123Z",
    "process_info": {
      "pid": 12345,
      "executable": "/usr/bin/target_app",
      "architecture": "x86_64"
    },
    "threads": [
      {
        "thread_id": 140234567890,
        "calls": [
          {
            "function": "main",
            "library": "/usr/bin/target_app",
            "address": "0x401000",
            "enter_time": "2025-08-15T10:30:00.001Z",
            "exit_time": "2025-08-15T10:30:05.120Z",
            "depth": 0,
            "children": [
              {
                "function": "init_system",
                "library": "/usr/lib/libsystem.so",
                "address": "0x7f8b12345000",
                "enter_time": "2025-08-15T10:30:00.002Z",
                "exit_time": "2025-08-15T10:30:00.050Z",
                "depth": 1,
                "children": []
              }
            ]
          }
        ]
      }
    ]
  }
}
```

#### ストリーミング出力実装
```c
// リアルタイム出力のための効率的なJSON生成
typedef struct json_writer {
    FILE* output_stream;
    size_t indent_level;
    bool first_element;
    circular_buffer_t* buffer;
} json_writer_t;

calltrace_error_t json_write_call_entry(json_writer_t* writer, const call_node_t* call) {
    // バッファリングによる効率的な出力
    if (writer->buffer->size > BUFFER_THRESHOLD) {
        flush_json_buffer(writer);
    }
    
    format_json_call(writer, call);
    return CALLTRACE_OK;
}
```

### 2.4 パフォーマンス最適化

#### メモリ管理戦略
```c
// オブジェクトプール
typedef struct object_pool {
    void* objects;
    size_t object_size;
    size_t pool_size;
    size_t allocated_count;
    bool* allocation_map;
    pthread_mutex_t mutex;
} object_pool_t;

// 高速メモリアロケーション
call_node_t* allocate_call_node(void) {
    static object_pool_t call_node_pool = {0};
    return (call_node_t*)pool_alloc(&call_node_pool);
}
```

#### ロックフリー実装
```c
// アトミック操作によるロックフリーカウンタ
typedef struct atomic_counter {
    volatile uint64_t value;
} atomic_counter_t;

static inline uint64_t atomic_increment(atomic_counter_t* counter) {
    return __sync_fetch_and_add(&counter->value, 1);
}

// ロックフリーリングバッファ
typedef struct lockfree_buffer {
    volatile size_t head;
    volatile size_t tail;
    size_t capacity;
    call_info_t* data;
} lockfree_buffer_t;
```

## 3. セキュリティ設計

### 3.1 権限管理
- 最小権限の原則適用
- setuid/setgidプログラムでの安全な動作
- SELinux/AppArmorポリシー準拠

### 3.2 メモリ安全性
```c
// バッファオーバーフロー対策
#define SAFE_STRNCPY(dest, src, size) do { \
    strncpy(dest, src, size - 1); \
    dest[size - 1] = '\0'; \
} while(0)

// スタック保護
#pragma GCC push_options
#pragma GCC optimize ("-fstack-protector-strong")
```

## 4. エラーハンドリング

### 4.1 エラー階層
```c
typedef enum {
    CALLTRACE_SEVERITY_INFO = 0,
    CALLTRACE_SEVERITY_WARNING = 1,
    CALLTRACE_SEVERITY_ERROR = 2,
    CALLTRACE_SEVERITY_FATAL = 3
} calltrace_severity_t;

typedef struct {
    calltrace_error_t code;
    calltrace_severity_t severity;
    const char* message;
    const char* file;
    int line;
    uint64_t timestamp;
} calltrace_error_info_t;
```

### 4.2 回復戦略
- グレースフルデグラデーション
- 部分的機能停止による継続動作
- 自動復旧メカニズム

## 5. 設定システム

### 5.1 設定階層
1. コンパイル時設定 (`config.h`)
2. 環境変数 (`CALLTRACE_*`)
3. 設定ファイル (`calltrace.conf`)
4. 実行時API (`calltrace_set_config`)

### 5.2 設定例
```bash
# 環境変数
export CALLTRACE_OUTPUT=/tmp/trace.json
export CALLTRACE_FILTER="main,init_*,cleanup_*"
export CALLTRACE_MAX_DEPTH=50
export CALLTRACE_BUFFER_SIZE=2048000

# 設定ファイル
output_file = "/tmp/calltrace.json"
filter_patterns = ["main", "init_*", "cleanup_*"]
max_depth = 50
enable_timestamps = true
enable_thread_info = true
```

## 6. 拡張性設計

### 6.1 プラグインアーキテクチャ
```c
typedef struct calltrace_plugin {
    const char* name;
    const char* version;
    calltrace_error_t (*init)(void);
    calltrace_error_t (*cleanup)(void);
    void (*on_call_entry)(const calltrace_call_info_t*);
    void (*on_call_exit)(const calltrace_call_info_t*);
} calltrace_plugin_t;
```

### 6.2 カスタム出力フォーマット
- XML出力サポート
- バイナリ出力フォーマット
- プロトコルバッファ対応

この設計により、高性能で拡張可能なコールトレースライブラリの実現を目指します。