# 機能設計書 3-トレース設定 ($/setTrace)

## 概要

本ドキュメントは、serve-d LSPサーバーにおけるトレース設定 ($/setTrace) 機能の設計を記述する。LSPクライアントからのトレースレベル変更通知を処理し、サーバーのログレベルを動的に切り替える。

### 本機能の処理概要

LSPプロトコルで定義された `$/setTrace` 通知を受け取り、サーバーのグローバルログレベルを切り替える。verboseが指定された場合はLogLevel.trace（詳細ログ）に、それ以外の場合はLogLevel.info（通常ログ）に設定する。

**業務上の目的・背景**：D言語開発者がserve-dの動作を調査・デバッグする際に、エディタから動的にログレベルを変更できる必要がある。サーバーの再起動なしにトレースレベルを切り替えられることで、問題発生時の迅速なログ収集が可能になる。

**機能の利用シーン**：エディタの設定でLSPサーバーのトレースレベルを変更した際に自動的に呼び出される。デバッグ時にverboseに切り替え、問題解決後にoffに戻す場面で利用される。

**主要な処理内容**：
1. SetTraceParamsからトレースレベル値を取得
2. TraceValue.verboseの場合、globalLogLevelをLogLevel.traceに設定
3. それ以外の場合、globalLogLevelをLogLevel.infoに設定

**関連システム・外部連携**：LSPクライアントからの通知。std.experimental.loggerのグローバルログレベル制御。

**権限による制御**：特に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | 設定変更通知 | 補助機能 | 設定変更処理内でログレベルの変更も処理する |

## 機能種別

システム制御（ログレベル動的変更）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| params | SetTraceParams | Yes | トレースレベル変更パラメータ | LSPプロトコル仕様に準拠 |
| params.value | TraceValue | Yes | 新しいトレースレベル | TraceValue列挙体の値（off / messages / verbose） |

### 入力データソース

LSPクライアントからのJSON-RPC通知（メソッド名: "$/setTrace"）

## 出力仕様

### 出力データ

通知処理のため、レスポンスは返却しない。

### 出力先

サーバー内部のglobalLogLevel（std.experimental.logger）に反映される。

## 処理フロー

### 処理シーケンス

```
1. トレースレベル判定
   └─ params.valueがTraceValue.verboseかどうか判定
2. ログレベル設定
   └─ verbose: globalLogLevel = LogLevel.trace
   └─ それ以外: globalLogLevel = LogLevel.info
```

### フローチャート

```mermaid
flowchart TD
    A[setTrace通知受信] --> B{value == verbose?}
    B -->|Yes| C[globalLogLevel = trace]
    B -->|No| D[globalLogLevel = info]
    C --> E[処理完了]
    D --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | verboseマッピング | TraceValue.verboseはLogLevel.traceにマッピングされる | value == verbose |
| BR-02 | 非verboseマッピング | verbose以外の全値はLogLevel.infoにマッピングされる | value != verbose |

### 計算ロジック

特になし。

## データベース操作仕様

本機能ではデータベース操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | エラーケースは存在しない | - |

### リトライ仕様

リトライは不要。

## トランザクション仕様

トランザクションは存在しない。

## パフォーマンス要件

即座に完了する軽量な処理。グローバル変数への代入のみ。

## セキュリティ考慮事項

ログレベル変更によりトレースログに機密情報が含まれる可能性があるが、serve-d自体では特別な制御は行わない。

## 備考

- initialize時にもparams.trace == "verbose"の場合にLogLevel.traceに設定される処理がある（extension.d 233-234行目）。
- @protocolNotification("$/setTrace")デコレータによりLSPルーターが自動ディスパッチする。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | protocol（LSP型定義） | LSP型定義 | SetTraceParams型: valueフィールド（TraceValue列挙体）を持つ |
| 1-2 | protocol（LSP型定義） | LSP型定義 | TraceValue列挙体: off, messages, verbose の3値 |

**読解のコツ**: SetTraceParamsとTraceValueはLSPプロトコルの標準型として `protocol/source/served/lsp/` 配下で定義されている。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | extension.d | `source/served/extension.d` | setTrace関数（1092-1099行目）: @protocolNotification("$/setTrace")でディスパッチされるハンドラ |

**主要処理フロー**:
1. **1095行目**: params.valueがTraceValue.verboseかどうか判定
2. **1096行目**: verbose → globalLogLevel = LogLevel.trace
3. **1098行目**: 非verbose → globalLogLevel = LogLevel.info

### プログラム呼び出し階層図

```
setTrace(SetTraceParams)  [@protocolNotification("$/setTrace")]
    |
    +-- globalLogLevel = LogLevel.trace  (verbose時)
    |
    +-- globalLogLevel = LogLevel.info   (非verbose時)
```

### データフロー図

```
[入力]                    [処理]                    [出力]

SetTraceParams ─────> setTrace()
  .value        ─────>   TraceValue判定
                         globalLogLevel設定 ─────> std.experimental.logger
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| extension.d | `source/served/extension.d` | ソース | setTrace関数の実装（1092-1099行目） |
