# 機能設計書 290-ConvertTo-DbaXESession

## 概要

本ドキュメントは、SQL Server Trace を Extended Events セッションに変換する ConvertTo-DbaXESession コマンドの機能設計書です。

### 本機能の処理概要

ConvertTo-DbaXESession は、既存の SQL Server Trace（SQL Trace）定義を解析し、イベント、カラム、アクション、フィルタを Extended Events の対応する要素にマッピングして、新しい Extended Events セッションを作成する PowerShell コマンドです。

**業務上の目的・背景**：SQL Trace（SQL Server Profiler）は SQL Server 2012 以降で非推奨となり、Extended Events への移行が推奨されています。しかし、長年使用してきたトレース定義を手動で Extended Events に変換するのは複雑で時間がかかります。本機能は、Jonathan M. Kehayias（SQLskills.com）の T-SQL 変換スクリプトを活用し、トレースイベントとカラムを自動的に Extended Events の対応要素にマッピングすることで、この移行作業を大幅に効率化します。

**機能の利用シーン**：
- 既存トレースの Extended Events への移行
- SQL Server バージョンアップグレード時の監視設定移行
- パフォーマンス監視の最新化
- 非推奨機能からの脱却
- コンプライアンス要件での監査設定更新

**主要な処理内容**：
1. 入力トレースオブジェクトの検証
2. SQL Server バージョンの確認（2012以降が必要）
3. 既存の同名セッションの重複チェック
4. sp_SQLskills_ConvertTraceToExtendedEvents を tempdb で実行
5. 生成された CREATE EVENT SESSION スクリプトの取得
6. Extended Events セッションの作成（またはスクリプト出力）
7. 作成されたセッションの取得と出力

**関連システム・外部連携**：Get-DbaTrace からのトレースオブジェクトを入力として受け取り、tempdb で変換用ストアドプロシージャを実行します。Get-DbaXESession で作成されたセッションを取得して出力します。

**権限による制御**：tempdb でのストアドプロシージャ作成・実行権限、および Extended Events セッションの作成権限（ALTER ANY EVENT SESSION）が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SSMS Extended Events | 結果表示画面 | 変換後セッション確認 |
| - | SQL Server Profiler | 参照画面 | 元トレース確認 |
| - | PowerShell Console | 主画面 | コマンド実行 |

## 機能種別

変換・移行操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| InputObject | object[] | Yes | Get-DbaTrace から取得したトレースオブジェクト | Id と Parent プロパティが必要 |
| Name | string | Yes | 作成する Extended Events セッション名 | - |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| OutputScriptOnly | switch | No | T-SQL スクリプトのみを出力 | - |
| EnableException | switch | No | 例外スロー有効化 | - |

### 入力データソース

- Get-DbaTrace からのパイプライン入力
- 変換用 SQL スクリプト（bin/sp_SQLskills_ConvertTraceToEEs.sql）

## 出力仕様

### 出力データ

OutputScriptOnly 指定時:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | string | CREATE EVENT SESSION T-SQL スクリプト |

通常出力:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Microsoft.SqlServer.Management.XEvent.Session | XEvent Session オブジェクト | 作成された Extended Events セッション |

Get-DbaXESession 経由で出力される場合、以下のプロパティが含まれます：

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server ホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Name | string | セッション名 |
| Status | string | セッション状態（Running/Stopped） |
| StartTime | DateTime | 開始日時 |
| AutoStart | bool | 自動開始フラグ |
| State | string | セッション状態 |
| Targets | array | ターゲット設定 |
| TargetFile | string | 出力ファイルパス |
| Events | array | 構成されたイベント |

### 出力先

PowerShell パイプライン（String または XEvent Session オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ 変換用 SQL スクリプト（sp_SQLskills_ConvertTraceToEEs.sql）の読み込み
2. 各トレースに対してループ処理
   ├─ トレースオブジェクトの検証（Id と Parent の存在確認）
   ├─ SQL Server バージョン確認（2012以降）
   ├─ 既存セッション名の重複チェック
   │   └─ 重複時はトレースID または乱数を追加
   ├─ SQL スクリプト内のプレースホルダ置換
   │   ├─ --TRACEID-- → トレースID
   │   └─ --SESSIONNAME-- → セッション名
   ├─ tempdb で変換 SQL を実行
   └─ 結果処理
       ├─ OutputScriptOnly → スクリプト出力
       └─ 通常 → セッション作成 + Get-DbaXESession で取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQL スクリプト読み込み]
    B --> C[InputObject ループ開始]
    C --> D{Id と Parent<br/>存在?}
    D -->|No| E[エラー: 入力タイプ不正]
    D -->|Yes| F{SQL Server<br/>バージョン >= 2012?}
    F -->|No| G[エラー: バージョン不足]
    F -->|Yes| H[既存セッション確認]
    H --> I{同名セッション<br/>存在?}
    I -->|Yes| J[名前にトレースID追加]
    J --> K{まだ重複?}
    K -->|Yes| L[名前に乱数追加]
    K -->|No| M[プレースホルダ置換]
    I -->|No| M
    L --> M
    M --> N[tempdb で変換 SQL 実行]
    N --> O{OutputScriptOnly?}
    O -->|Yes| P[スクリプト出力]
    O -->|No| Q[セッション作成実行]
    Q --> R[Get-DbaXESession]
    R --> S[セッション出力]
    P --> C
    S --> C
    C -->|完了| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力検証 | InputObject には Id と Parent プロパティが必要 | 常時 |
| BR-002 | バージョン要件 | SQL Server 2012（バージョン11）以降が必要 | 常時 |
| BR-003 | 名前重複回避 | 既存セッションと重複時はトレースIDまたは乱数を追加 | セッション作成時 |
| BR-004 | 変換マッピング | SQLskills の変換テーブルを使用してイベント・カラムをマッピング | 常時 |

### 計算ロジック

名前重複回避:
```
1. 既存セッション確認
2. 重複時: Name = Name + "-" + TraceId
3. まだ重複時: Name = Name + "-" + Random()
```

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

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 変換処理 | tempdb（一時テーブル） | CREATE/INSERT/SELECT | 変換マッピングテーブルの作成と使用 |
| セッション作成 | sys.server_event_sessions | INSERT | CREATE EVENT SESSION 実行 |

### テーブル別操作詳細

#### tempdb.#SQLskills_Trace_XE_Column_Map

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE | trace_event_id, trace_column_id, xe_event_name 等 | - | 変換マッピング用 |
| INSERT | 各マッピング定義 | sys.trace_* から生成 | - |
| SELECT | SqlString | トレースID条件 | 変換結果取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力タイプエラー | InputObject が不正 | Get-DbaTrace を使用 |
| - | バージョンエラー | SQL Server 2012 未満 | SQL Server 2012以降を使用 |
| - | 変換実行エラー | tempdb でのスクリプト実行失敗 | エラーメッセージを確認 |
| - | セッション作成エラー | CREATE EVENT SESSION 失敗 | 権限と構文を確認 |

### リトライ仕様

リトライは実装されていません。失敗時は Stop-Function でエラー出力します。

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

tempdb でのマッピングテーブル作成と変換処理は自動トランザクションで実行されます。セッション作成は別トランザクションです。

## パフォーマンス要件

特に定義されていません。トレースの複雑さに応じて変換時間が変わります。

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

- tempdb での操作権限が必要
- ALTER ANY EVENT SESSION 権限が必要
- 変換元トレースの設定をそのまま引き継ぐため、フィルタ設定も保持される

## 備考

- SQL Server 2012 以降をサポート
- Jonathan M. Kehayias（SQLskills.com）の T-SQL スクリプトを使用
- Gianluca Sartori と Chrissy LeMaire による最適化
- Linux 対応のパスセパレータ処理を含む

---

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

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

### 推奨読解順序

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

変換マッピングの仕組みを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_SQLskills_ConvertTraceToEEs.sql | `bin/sp_SQLskills_ConvertTraceToEEs.sql` | マッピングテーブルの構造と変換ロジック |

**読解のコツ**: #SQLskills_Trace_XE_Column_Map 一時テーブルが trace_event_id を xe_event_name にマッピングしていることを確認します。

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

パラメータ定義と begin ブロックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | パラメータ定義と SQL スクリプト読み込み |

**主要処理フロー**:
1. **101-110行目**: パラメータ定義（InputObject, Name, OutputScriptOnly 等）
2. **111-114行目**: begin ブロックで SQL スクリプト読み込み

#### Step 3: 変換処理の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | process ブロックのメインロジック |

**主要処理フロー**:
- **117-120行目**: InputObject の検証
- **124-127行目**: SQL Server バージョン確認
- **140-151行目**: セッション名重複チェックと修正
- **153-154行目**: プレースホルダ置換
- **156-161行目**: tempdb で変換 SQL 実行
- **165-182行目**: 結果処理（スクリプト出力またはセッション作成）

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

```
ConvertTo-DbaXESession
    │
    ├─ [begin]
    │      └─ Get-Content sp_SQLskills_ConvertTraceToEEs.sql
    │
    └─ [process]
           └─ foreach Trace
                  │
                  ├─ 入力検証 (Id, Parent)
                  │
                  ├─ バージョン確認 (>= 11)
                  │
                  ├─ Get-DbaXESession (重複チェック)
                  │
                  ├─ プレースホルダ置換
                  │      ├─ --TRACEID-- → $traceid
                  │      └─ --SESSIONNAME-- → $name
                  │
                  ├─ tempdb.ExecuteWithResults(sql)
                  │      └─ 変換マッピング実行
                  │
                  ├─ [OutputScriptOnly]
                  │      └─ スクリプト出力
                  │
                  └─ [通常]
                         ├─ tempdb.ExecuteNonQuery(results)
                         └─ Get-DbaXESession
```

### データフロー図

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

Get-DbaTrace ──────┐
     │             │
     ▼             │
InputObject ───────┼──▶ 入力検証
     │             │       │
Name ──────────────┤       ▼
     │             │   バージョン確認
SqlCredential ─────┤       │
     │             │       ▼
OutputScriptOnly ──┘   重複チェック
                           │
                           ▼
                    sp_SQLskills_ConvertTraceToEEs.sql
                           │
                           ├──▶ プレースホルダ置換
                           │
                           └──▶ tempdb.ExecuteWithResults
                                      │
                                      ▼
                               CREATE EVENT SESSION スクリプト
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
                    ▼                                   ▼
            [OutputScriptOnly]                    [通常]
                    │                                   │
                    ▼                                   ▼
            String 出力 ──▶ パイプライン    ExecuteNonQuery
                                                        │
                                                        ▼
                                              Get-DbaXESession
                                                        │
                                                        ▼
                                              XEvent Session ──▶ パイプライン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | ソース | メイン関数実装 |
| ConvertTo-DbaXESession.Tests.ps1 | `tests/ConvertTo-DbaXESession.Tests.ps1` | テスト | ユニット・統合テスト |
| sp_SQLskills_ConvertTraceToEEs.sql | `bin/sp_SQLskills_ConvertTraceToEEs.sql` | SQL | 変換用 T-SQL スクリプト |
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | ソース | トレース取得（依存） |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | XE セッション取得（依存） |
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | ソース | XE セッション開始（関連） |
| Remove-DbaXESession.ps1 | `public/Remove-DbaXESession.ps1` | ソース | XE セッション削除（関連） |
