# 通知設計書 10-$/setTrace

## 概要

本ドキュメントは、LSP(Language Server Protocol)における$/setTrace通知の設計仕様を記載する。クライアントからサーバーへ送信される通知であり、トレースレベルの設定を通知する。

### 本通知の処理概要

$/setTrace通知は、クライアントがサーバーのトレースレベルを変更する際に送信される通知である。トレースレベルの変更により、サーバーは送受信メッセージの詳細度を調整し、デバッグや問題調査を支援する。

**業務上の目的・背景**：LSPサーバーの開発やトラブルシューティングにおいて、クライアントとサーバー間の通信内容を確認する必要がある。トレースレベルを動的に変更することで、必要な時だけ詳細なログを取得し、パフォーマンスへの影響を最小限に抑えながらデバッグを行うことができる。

**通知の送信タイミング**：クライアントがトレース設定を変更した時（例：エディタのデバッグ設定変更、トレースコマンド実行）、またはinitializeリクエストでトレースレベルを指定した後に動的に変更する場合に送信される。

**通知の受信者**：clojure-lspサーバープロセスがこの通知を受信する。

**通知内容の概要**：通知には、新しいトレースレベル（off/messages/verbose）が含まれる。

**期待されるアクション**：サーバーは受信後、jsonrpc.server/set-trace-level関数を呼び出し、サーバーのトレースレベルを更新する。これにより、以降のメッセージ処理においてトレース出力の詳細度が変更される。

## 通知種別

LSP通知 (クライアント → サーバー)

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即座に処理） |
| 優先度 | 低（デバッグ用） |
| リトライ | なし（通知のため応答なし） |

### 送信先決定ロジック

クライアントからサーバーへの一方向通知のため、送信先決定ロジックは不要。

## 通知テンプレート

### パラメータ構造

| 項目 | 内容 |
|-----|------|
| メソッド名 | $/setTrace |
| パラメータ型 | SetTraceParams |
| プロトコル | JSON-RPC 2.0 over stdio |

### パラメータ定義

```json
{
  "value": "verbose"
}
```

### トレースレベル値

| 値 | 説明 |
|-----|------|
| off | トレース無効 |
| messages | メッセージ内容のみ |
| verbose | 詳細なトレース（パラメータ含む） |

### 添付ファイル

該当なし（LSP通知にファイル添付機能なし）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| value | トレースレベル | クライアント（設定） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 設定変更 | デバッグ設定変更 | サーバー接続中 | ユーザーがトレース設定を変更した時 |
| コマンド | トレースコマンド実行 | サーバー接続中 | デバッグコマンドによるトレース変更 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| サーバー未接続 | LSPサーバーが起動していない/接続されていない場合 |
| 初期化未完了 | initializeリクエストが完了していない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[トレース設定変更] --> B[$/setTrace通知送信]
    B --> C[サーバーで受信]
    C --> D[valueパラメータを取得]
    D --> E[jsonrpc.server/set-trace-levelを呼び出し]
    E --> F[トレースレベル更新]
    F --> G[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（サーバー状態のみ変更）

### 更新テーブル一覧

該当なし（サーバー状態のみ変更）

### サーバー状態の更新

| 項目 | 更新内容 | 備考 |
|-----|---------|------|
| trace-level | 新しいトレースレベル | jsonrpc.serverの内部状態 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 不正なトレースレベル | off/messages/verbose以外の値 | エラーログ出力 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（通知のためリトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（常時処理可能）

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

- トレースレベルをverboseに設定すると、通信内容がログに記録される可能性がある
- センシティブな情報（APIキー、認証情報等）がトレースログに出力されないよう注意が必要
- トレースログはサーバーのログファイルに記録される

## 備考

- LSP仕様: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#setTrace
- この通知は応答を返さない(notification)
- $/プレフィックスはLSP固有の通知/リクエストを示す
- initializeリクエストでもtraceパラメータでトレースレベルを設定可能

---

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

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

### 推奨読解順序

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

まず、プログラム間で受け渡されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | なし | - | SetTraceParamsは単純な{:value "level"}構造 |

**読解のコツ**: トレースレベルは文字列（"off", "messages", "verbose"）で渡される。

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

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | server.clj | `cli/src/clojure_lsp/server.clj` | receive-notification multimethod定義 |

**主要処理フロー**:
1. **582-585行目**: `$/setTrace`メソッドのdefmethod定義
2. **582行目**: {:keys [value]}でパラメータ分解
3. **583-585行目**: jsonrpc.server/set-trace-levelの呼び出し

#### Step 3: トレースレベル設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | server.clj | `cli/src/clojure_lsp/server.clj` | shared/logging-taskマクロ使用 |

**主要処理フロー**:
- **583-585行目**: logging-taskで:set-traceタスクとしてログ記録
- **585行目**: jsonrpc.server/set-trace-level関数呼び出し

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

```
jsonrpc.server/receive-notification "$/setTrace"
    |
    +-- server.clj (582-585行目)
           |
           +-- パラメータ分解 {:keys [value]}
           |
           +-- shared/logging-task :set-trace
                  |
                  +-- jsonrpc.server/set-trace-level (server, value)
                         |
                         +-- サーバーのトレースレベル更新
```

### データフロー図

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

SetTraceParams
    |
    +-- value ------+
         |          |
         v          v
    ["off" |   receive-notification
    "messages" |          |
    "verbose"]           v
                   logging-task :set-trace
                         |
                         v
                   jsonrpc.server/set-trace-level
                         |
                         v
                   サーバー内部状態更新
                         |
                         v
                   トレース出力レベル変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| server.clj | `cli/src/clojure_lsp/server.clj` | ソース | LSPサーバーのエントリーポイント、通知受信 |
| shared.clj | `lib/src/clojure_lsp/shared.clj` | ソース | logging-taskマクロ |
| jsonrpc4clj | `依存ライブラリ` | 外部ライブラリ | JSON-RPCサーバー実装、set-trace-level関数 |
