# 機能設計書 309-Start-DbaXESession

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Start-DbaXESession` コマンドレットの機能設計を記述する。このコマンドレットは、SQL Serverインスタンス上の拡張イベント(Extended Events)セッションを開始する機能を提供する。

### 本機能の処理概要

`Start-DbaXESession` は、作成済みだが実行されていない拡張イベントセッションを開始するコマンドレットである。個別のセッションを名前で開始、全ユーザーセッションを一括開始、または指定時刻に開始/停止するスケジュール実行が可能である。

**業務上の目的・背景**：拡張イベントセッションはSQL Serverの軽量監視フレームワークであり、パフォーマンス問題のトラブルシューティング、セキュリティ監査、特定のデータベースアクティビティパターンのキャプチャに使用される。本機能により、セッションの開始を自動化し、特定の時間窓でのデータ収集や時間外トラブルシューティングを実現できる。

**機能の利用シーン**：
- 作成済みのXEセッションを開始したい場合
- 全ユーザーセッションを一括で開始したい場合
- 特定の時刻にセッションを開始/停止するスケジュールを設定したい場合
- Get-DbaXESessionでフィルタリングしたセッションを開始したい場合
- 夜間バッチ処理中の監視セッションを自動化したい場合

**主要な処理内容**：
1. 対象セッションの取得（Get-DbaXESession）
2. セッションフィルタリング（Session指定またはAllSessions）
3. AllSessions時はシステムセッションを除外
4. 即時開始またはスケジュールジョブ作成
5. StopAt指定時は停止用ジョブも作成
6. セッション開始後、更新されたセッション情報を出力

**関連システム・外部連携**：SQL Server Agentジョブを使用したスケジュール実行。Get-DbaXESession でセッション取得、New-DbaAgentJob/New-DbaAgentSchedule でジョブ作成。

**権限による制御**：sysadmin権限が必要。スケジュール実行にはSQL Server Agentが必要。システムセッションは自動的に保護される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | XEセッション管理 | 補助機能 | 拡張イベントセッションの開始 |

## 機能種別

状態変更処理（START）/ スケジュール作成（CREATE JOB）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes（ParameterSet: Session/All） | 接続先SQLインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Session | object[] | Yes（ParameterSet: Session） | 開始対象セッション名 | - |
| AllSessions | switch | Yes（ParameterSet: All） | 全ユーザーセッション開始 | - |
| InputObject | Microsoft.SqlServer.Management.XEvent.Session[] | Yes（ParameterSet: Object） | パイプライン入力セッション | - |
| StartAt | datetime | No | スケジュール開始日時 | - |
| StopAt | datetime | No | スケジュール停止日時 | - |
| WhatIf | switch | No | 実行せずに動作を表示 | - |
| Confirm | switch | No | 実行前に確認 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- ユーザー指定のセッション名
- Get-DbaXESessionからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQLインスタンスのコンピューター名 |
| InstanceName | String | SQLインスタンス名 |
| SqlInstance | String | 完全修飾インスタンス名 |
| Name | String | セッション名 |
| Status | String | セッションステータス（Running/Stopped） |
| StartTime | DateTime | セッション開始日時 |
| AutoStart | Boolean | 自動開始設定 |
| State | String | SMOオブジェクト状態 |
| Targets | Collection | ターゲットコレクション |
| TargetFile | String[] | ターゲットファイルパス |
| Events | Collection | イベントコレクション |
| MaxMemory | Int | 最大メモリ（KB） |
| MaxEventSize | Int | 最大イベントサイズ（KB） |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.XEvent.Session）

## 処理フロー

### 処理シーケンス

```
1. パラメータセット判定
2. InputObject処理 または SqlInstance処理
3. セッションフィルタリング
   └─ Session指定: 名前でフィルタ
   └─ AllSessions: システムセッション除外
4. ShouldProcess確認
5. StartAt指定時
   └─ New-Job でスケジュールジョブ作成
   └─ セッションオブジェクトを返却
6. StartAt未指定時
   └─ Start-XESessions でセッション開始
7. StopAt指定時
   └─ New-Job で停止用ジョブ作成
8. Get-DbaXESession で更新されたセッション情報を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject指定?}
    B -->|Yes| C[Start-XESessions]
    B -->|No| D[各インスタンスを処理]
    D --> E[Get-DbaXESession]
    E --> F{Session指定?}
    F -->|Yes| G[名前でフィルタ]
    F -->|No| H{AllSessions?}
    H -->|Yes| I[システムセッション除外]
    G --> J{ShouldProcess?}
    I --> J
    J -->|Yes| K{StartAt指定?}
    J -->|No| L[終了]
    K -->|Yes| M[New-Job START]
    K -->|No| N[Start-XESessions]
    M --> O[セッション出力]
    N --> O
    O --> P{StopAt指定?}
    P -->|Yes| Q[New-Job STOP]
    P -->|No| L
    Q --> L
    C --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-309-01 | システムセッション保護 | system_health、telemetry_xevents、AlwaysOn_healthは対象外 | AllSessions使用時 |
| BR-309-02 | 実行中セッションのスキップ | 既に実行中のセッションは警告のみ | 常時 |
| BR-309-03 | スケジュールジョブ削除 | ジョブ実行後は自動削除（DeleteLevel: Always） | StartAt/StopAt使用時 |
| BR-309-04 | SQLコマンド生成 | ALTER EVENT SESSION ON SERVER STATE = START/STOP | スケジュール実行時 |

### 計算ロジック

- システムセッションリスト: `@('AlwaysOn_health', 'system_health', 'telemetry_xevents')`
- ジョブ名: `"XE Session $Action - $session"`
- SQLコマンド: `"ALTER EVENT SESSION [$session] ON SERVER STATE = $Action;"`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 開始 | XEセッション | ALTER STATE | 拡張イベントセッション開始 |
| 作成 | SQLエージェントジョブ | INSERT | スケジュールジョブ作成 |

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

#### 拡張イベントセッション

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| ALTER | State | START | SMO Start()経由または ALTER文 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | StartError | セッション開始失敗 | Stop-Functionで継続 |
| - | AlreadyRunning | セッションが既に実行中 | 警告メッセージ出力 |

### リトライ仕様

なし

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

なし（各セッションを個別に開始）

## パフォーマンス要件

- セッション数に比例した処理時間

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

- sysadmin権限が必要
- スケジュール実行にはSQL Server Agent権限が必要

## 備考

- Get-DbaXESession と組み合わせて柔軟なフィルタリングが可能
- StartAt/StopAtで時間窓を指定したデータ収集が可能
- スケジュールジョブは実行後に自動削除される

---

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

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

### 推奨読解順序

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

出力オブジェクト（Sessionオブジェクト）の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | OUTPUTSセクション（63-88行目） |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.XEvent.Sessionオブジェクト。開始後の状態が反映される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | begin ブロック（140-196行目） |
| 2-2 | Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | process ブロック（198-226行目） |

**主要処理フロー**:
1. **142-164行目**: Start-XESessions内部関数
2. **166-196行目**: New-Job内部関数
3. **199-200行目**: InputObject処理
4. **202-225行目**: SqlInstance処理

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | Start-XESessions関数（142-164行目） |
| 3-2 | Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | New-Job関数（166-196行目） |

**主要処理フロー**:
- **150行目**: IsRunningチェック
- **154行目**: Start()呼び出し
- **162行目**: Get-DbaXESessionで更新情報取得
- **183-185行目**: スケジュール作成
- **188行目**: ジョブ作成（DeleteLevel: Always）
- **191-193行目**: ジョブステップ作成

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

```
Start-DbaXESession
    │
    ├─ Get-DbaXESession
    │
    ├─ Where-Object（Session/AllSessionsフィルタ）
    │
    ├─ Start-XESessions（内部関数）
    │      │
    │      ├─ $xe.Start()
    │      │
    │      └─ Get-DbaXESession（更新情報取得）
    │
    └─ New-Job（内部関数）
           │
           ├─ New-DbaAgentSchedule
           │
           ├─ New-DbaAgentJob
           │
           └─ New-DbaAgentJobStep
```

### データフロー図

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

InputObject ─────────────▶ Start-XESessions ───────▶ Session[]

SqlInstance ─────────────▶ Get-DbaXESession
      │                          │
      ▼                          ▼
Session Filter ──────────▶ Where-Object Name -in
      │                          │
AllSessions Filter ──────▶ Where-Object Name -notin システムセッション
                                  │
                                  ▼
                          ShouldProcess確認
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                        │
          ▼                       ▼                        ▼
     StartAt指定             StartAt未指定            StopAt指定
          │                       │                        │
          ▼                       ▼                        ▼
     New-Job START         Start-XESessions          New-Job STOP
          │                       │
          └───────────────────────┤
                                  ▼
                          Session Object ─────────────▶ Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | ソース | メインコマンドレット |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション取得（依存先） |
| New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | ソース | ジョブ作成（依存先） |
| New-DbaAgentSchedule.ps1 | `public/New-DbaAgentSchedule.ps1` | ソース | スケジュール作成（依存先） |
| New-DbaAgentJobStep.ps1 | `public/New-DbaAgentJobStep.ps1` | ソース | ジョブステップ作成（依存先） |
