# 画面設計書 89-XEセッション変換

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL TraceからExtended Eventsへの変換機能の設計仕様を定義する。既存のSQL Traceを解析し、同等の監視機能を持つXEセッションに変換するCLIを提供する。

### 本画面の処理概要

本機能は、レガシーなSQL Trace（SQL Server Profiler）の定義をExtended Eventsセッションに変換するためのコマンドラインインターフェースを提供する。トレースイベント、カラム、フィルターをXEの対応するイベント、アクション、述語にマッピングする。

**業務上の目的・背景**：SQL Traceは非推奨となり、Extended Eventsへの移行が推奨されている。しかし、手動での変換は複雑で時間がかかる。本機能は、Jonathan M. Kehayiasの変換ストアドプロシージャ（sp_SQLskills_ConvertTraceToExtendedEvents）を活用し、トレースイベントとXEイベントの包括的なマッピングを自動化する。これにより、既存の監視構成を維持しながらXEへの移行を効率化する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaTrace -SqlInstance <インスタンス名> | ConvertTo-DbaXESession -Name <セッション名>`
- `Get-DbaTrace -SqlInstance <インスタンス名> | ConvertTo-DbaXESession -Name <セッション名> -OutputScriptOnly`

**主要な操作・処理内容**：
1. SQL Traceオブジェクトの受け取り
2. トレースイベント・カラム・フィルターの解析
3. XEイベント・アクション・述語へのマッピング
4. CREATE EVENT SESSION T-SQLの生成
5. XEセッションの作成と開始（オプション）

**画面遷移**：
- 入力元：`Get-DbaTrace`からパイプライン入力
- 出力先：`Start-DbaXESession`でセッション開始可能

**権限による表示制御**：sysadmin権限が必要。tempdbでのストアドプロシージャ実行権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|-------------------|
| 142 | ConvertTo-DbaXESession | 主機能 | Trace→XE変換 |
| 293 | Get-DbaTrace | 遷移元機能 | SQL Trace取得 |
| 440 | Start-DbaXESession | 遷移先機能 | XEセッション開始 |

## 画面種別

コマンドラインインターフェース（CLI） / 変換・マイグレーション

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaTrace -SqlInstance <インスタンス名> | ConvertTo-DbaXESession -Name <セッション名>`
- `Get-DbaTrace -SqlInstance <インスタンス名> -Id <ID> | ConvertTo-DbaXESession -Name <セッション名>`
- `Get-DbaTrace -SqlInstance <インスタンス名> | ConvertTo-DbaXESession -Name <セッション名> -OutputScriptOnly`

## 入出力項目

### ConvertTo-DbaXESession 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| InputObject | object[] | はい | SQL Traceオブジェクト（Get-DbaTraceから取得） |
| Name | string | はい | 新しいXEセッション名 |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| OutputScriptOnly | switch | いいえ | T-SQLスクリプトのみ出力 |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

### ConvertTo-DbaXESession 出力オブジェクト（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Name | string | XEセッション名 |
| Status | string | 状態（Running/Stopped） |
| StartTime | datetime | 開始日時 |
| AutoStart | bool | 自動開始フラグ |
| State | string | セッション状態 |
| Targets | Collection | ターゲットコレクション |
| TargetFile | string[] | ターゲットファイルパス |
| Events | Collection | イベントコレクション |
| MaxMemory | int | 最大メモリ（MB） |
| MaxEventSize | int | 最大イベントサイズ（KB） |

### ConvertTo-DbaXESession 出力オブジェクト（-OutputScriptOnly指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| （文字列） | string | CREATE EVENT SESSION T-SQL |

## イベント仕様

### 1-Trace→XE変換（ConvertTo-DbaXESession）

1. sp_SQLskills_ConvertTraceToEEs.sqlを読み込み
2. 入力オブジェクトの検証（idとParentプロパティの存在確認）
3. SQL Serverバージョン確認（2012以降が必要）
4. 同名XEセッションの存在確認（存在時は名前変更）
5. トレースIDとセッション名をSQLに埋め込み
6. tempdbで変換SQLを実行
7. 結果のCREATE EVENT SESSION T-SQLを取得
8. OutputScriptOnlyの場合：T-SQLを出力
9. 通常モードの場合：tempdb.ExecuteNonQuery()でセッション作成
10. Get-DbaXESessionで作成されたセッションを取得して出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| sp_SQLskills_ConvertTraceToExtendedEvents | tempdb.dbo.(一時テーブル) | 一時使用 | マッピング処理 |
| CREATE EVENT SESSION | sys.server_event_sessions | INSERT | XEセッション作成 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | Input is of the wrong type. Use Get-DbaTrace. | 不正な入力オブジェクト |
| MSG002 | エラー | SQL Server version 2012+ required - {server} not supported. | バージョン非対応 |
| MSG003 | 情報 | XE Session {name} already exists on {server}, trying {newname}. | 同名セッション存在 |
| MSG004 | エラー | Issue creating, dropping or executing sp_SQLskills_ConvertTraceToExtendedEvents in tempdb on {server}. | 変換SQL実行エラー |
| MSG005 | エラー | Issue creating extended event {name} on {server}. | セッション作成エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 不正な入力オブジェクト | Stop-Functionでエラーを表示し、次のトレースに継続 |
| バージョン非対応（2012未満） | Stop-Functionでエラーを表示し処理を停止 |
| 変換SQL実行エラー | Stop-Functionでエラーを表示 |
| セッション作成エラー | Stop-Functionでエラーを表示 |
| 同名セッション存在 | セッション名を変更して再試行 |

## 備考

- SQL Server 2012以降が必要（VersionMajor >= 11）
- 変換ロジックはJonathan M. Kehayias（SQLskills.com）作成のT-SQLを使用
- 同名セッション存在時の名前変更ロジック：
  1. 最初の試行：`{Name}-{TraceID}`
  2. 2回目の試行：`{Name}-{RandomNumber}`
- トレースイベントのマッピング例：
  - RPC:Completed → rpc_completed
  - SQL:BatchCompleted → sql_batch_completed
  - Lock:Acquired → lock_acquired
  - Lock:Released → lock_released
- tempdbでストアドプロシージャを作成・実行する
- OutputScriptOnlyを使用すると、コンプライアンス環境でのレビュー後に手動実行可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | 出力オブジェクトの構造（51-84行目）を確認 |

**読解のコツ**: デフォルト出力はGet-DbaXESessionの戻り値。OutputScriptOnly時はT-SQL文字列。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | param()ブロック（102-110行目）で入力パラメータを確認 |

**主要処理フロー**:
1. **112-113行目**: 変換SQLファイルの読み込み
2. **117-120行目**: 入力オブジェクトの検証
3. **124-127行目**: SQL Serverバージョン確認
4. **140-151行目**: 同名セッションの確認と名前変更

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | 変換SQL実行（153-161行目） |
| 3-2 | sp_SQLskills_ConvertTraceToEEs.sql | `bin/sp_SQLskills_ConvertTraceToEEs.sql` | 変換ロジック本体 |

**主要処理フロー**:
- **153-154行目**: トレースIDとセッション名をSQLに埋め込み
- **158行目**: tempdb.ExecuteWithResults()で変換SQL実行
- **163行目**: 結果を改行で結合

#### Step 4: セッション作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | セッション作成（165-182行目） |

**主要処理フロー**:
- **165-166行目**: OutputScriptOnlyの場合はT-SQLを出力
- **170行目**: tempdb.ExecuteNonQuery()でセッション作成
- **181行目**: Get-DbaXESessionで作成されたセッションを取得

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

```
ConvertTo-DbaXESession
    │
    ├─ Get-Content (sp_SQLskills_ConvertTraceToEEs.sql)
    │      └─ 変換SQLを読み込み
    │
    ├─ 入力検証
    │      ├─ id/Parentプロパティ確認
    │      └─ VersionMajor >= 11 確認
    │
    ├─ Get-DbaXESession (同名セッション確認)
    │      └─ 存在時は名前変更
    │
    ├─ tempdb.ExecuteWithResults()
    │      └─ 変換SQL実行 → CREATE EVENT SESSION T-SQL
    │
    ├─ OutputScriptOnly?
    │      ├─ Yes → T-SQL出力
    │      └─ No → tempdb.ExecuteNonQuery()
    │                     │
    │                     ▼
    │              セッション作成
    │
    └─ Get-DbaXESession
           └─ 作成されたセッションを取得・出力
```

### データフロー図

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

InputObject ─────▶ 入力検証
(Get-DbaTrace)            │
      │           id/Parentプロパティ確認
      │                   │
      │           VersionMajor >= 11
      │                   │
      ▼                   ▼
trace.Parent ────▶ SMO Server
      │                   │
      │                   ▼
trace.id ────────▶ SQL置換 (--TRACEID--)
      │                   │
Name ────────────▶ SQL置換 (--SESSIONNAME--)
      │                   │
      │           同名セッション確認
      │                   │
      │           名前変更（必要時）
      │                   │
      ▼                   ▼
sp_SQLskills_ConvertTraceToEEs.sql
      │
      ▼
tempdb.ExecuteWithResults()
      │
      ▼ CREATE EVENT SESSION T-SQL
      │
      │         ┌───────────────────────┐
      │         │                       │
      ▼         ▼                       ▼
OutputScriptOnly?               tempdb.ExecuteNonQuery()
      │                                │
      ▼                                ▼
  String                    sys.server_event_sessions
  (T-SQL)                              │
                                       ▼
                              Get-DbaXESession
                                       │
                                       ▼
                              XEvent.Session Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaXESession.ps1 | `public/ConvertTo-DbaXESession.ps1` | ソース | Trace→XE変換 |
| sp_SQLskills_ConvertTraceToEEs.sql | `bin/sp_SQLskills_ConvertTraceToEEs.sql` | データ | 変換SQLスクリプト |
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | 依存 | SQL Trace取得 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | 依存 | XEセッション取得 |
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | 関連 | XEセッション開始 |
