# 機能設計書 175-Invoke-DbaWhoIsActive

## 概要

本ドキュメントは、dbatools PowerShellモジュールのInvoke-DbaWhoIsActive関数の機能設計を定義する。アクティブなSQL Serverセッションと現在実行中のクエリに関するリアルタイム情報を取得する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Adam Machanicのsp_WhoIsActiveストアドプロシージャを実行して、現在実行中のセッション、アクティブなクエリ、およびそれらのリソース消費に関する詳細情報を表示する。パフォーマンス問題のトラブルシューティング、ブロッキングチェーンの特定、およびSQL Serverアクティビティのリアルタイム監視に最適なコマンド。複数のDMVを手動でクエリする代わりに、包括的なセッション詳細を取得できる。

**機能の利用シーン**：
- 本番環境でのリアルタイムパフォーマンス監視
- ブロッキング問題の特定と解決
- 長時間実行クエリの検出
- CPU/メモリ使用量が高いセッションの特定
- トランザクションログ使用状況の監視
- 実行プランの取得と分析

**主要な処理内容**：
1. SQL Server 2005以上への接続確認
2. sp_WhoIsActiveストアドプロシージャのパラメータ構築
3. Invoke-DbaQueryを使用してストアドプロシージャを実行
4. 結果を指定フォーマット（DataRow/PSObject等）で出力

**関連システム・外部連携**：Adam Machanicのsp_WhoIsActiveストアドプロシージャ（Install-DbaWhoIsActiveでインストール）。http://whoisactive.com で詳細情報が公開されている。

**権限による制御**：VIEW SERVER STATE権限が必要。一部の機能（GetLocks、GetPlans等）には追加の権限が必要な場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに登録なし |

## 機能種別

監視 / セッション分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | Mandatory, ValueFromPipeline |
| SqlCredential | PSCredential | No | 接続資格情報 | - |
| Database | string | No | sp_WhoIsActiveがインストールされているDB | デフォルト: master |
| Filter | string | No | 結果フィルタ | ValidateLength(0,128) |
| FilterType | string | No | フィルタタイプ | ValidateSet |
| NotFilter | string | No | 除外フィルタ | ValidateLength(0,128) |
| NotFilterType | string | No | 除外フィルタタイプ | ValidateSet |
| ShowOwnSpid | switch | No | 自セッションを含める | - |
| ShowSystemSpids | switch | No | システムセッションを含める | - |
| ShowSleepingSpids | int | No | スリープセッション表示レベル（0/1/2） | ValidateRange(0,255) |
| GetFullInnerText | switch | No | 完全なバッチテキストを取得 | - |
| GetPlans | int | No | 実行プラン取得（1/2） | ValidateRange(0,255) |
| GetOuterCommand | switch | No | 外部コマンドを取得 | - |
| GetTransactionInfo | switch | No | トランザクション情報を取得 | - |
| GetTaskInfo | int | No | タスク情報レベル（0/1/2） | ValidateRange(0,2) |
| GetLocks | switch | No | ロック情報を取得 | - |
| GetAverageTime | switch | No | 平均実行時間を計算 | - |
| GetAdditonalInfo | switch | No | 追加のセッション設定情報 | - |
| FindBlockLeaders | switch | No | ブロッキングの根本原因を特定 | - |
| DeltaInterval | int | No | 差分計測間隔（秒） | ValidateRange(0,255) |
| OutputColumnList | string | No | 出力列リスト | デフォルト設定あり |
| SortOrder | string | No | ソート順 | デフォルト: start_time ASC |
| FormatOutput | int | No | 出力フォーマット（0/1/2） | ValidateRange(0,255) |
| DestinationTable | string | No | 結果出力先テーブル | ValidateLength(0,4000) |
| ReturnSchema | switch | No | CREATE TABLE文を返す | - |
| Schema | string | No | ReturnSchemaのエイリアス | - |
| Help | switch | No | ヘルプ情報を返す | - |
| As | string | No | 出力フォーマット | ValidateSet |
| EnableException | switch | No | 例外をスローするか | - |

### 入力データソース

- SqlInstanceパラメータで指定されたSQL Serverインスタンス
- sp_WhoIsActiveストアドプロシージャ（事前インストール必要）

## 出力仕様

### 出力データ

基本列:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| session_id | int | セッションID |
| sql_text | string | 実行中のSQLテキスト |
| login_name | string | ログイン名 |
| start_time | datetime | 開始時刻 |
| status | string | セッションステータス |
| host_name | string | クライアントホスト名 |

オプション列（機能パラメータ有効時）:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| query_plan | XML | 実行プラン（GetPlans有効時） |
| locks | XML | ロック情報（GetLocks有効時） |
| tran_log_used_percent | decimal | トランザクションログ使用率（GetTransactionInfo有効時） |
| wait_info | string | 待機情報（GetTaskInfo有効時） |
| avg_elapsed_time_ms | int | 平均実行時間（GetAverageTime有効時） |

### 出力先

- 標準出力（パイプライン）にAsパラメータで指定した形式で出力
- DestinationTable指定時は指定テーブルに挿入

## 処理フロー

### 処理シーケンス

```
1. beginブロック: パラメータ準備
   ├─ 渡されたパラメータをフィルタリング
   └─ FilterType/NotFilterTypeを小文字に変換

2. processブロック開始
   ├─ 各インスタンスに対して接続（MinimumVersion 9指定）
   └─ パラメータ辞書からSQL用パラメータを構築

3. パラメータマッピング
   ├─ PowerShellパラメータ名 → sp_WhoIsActiveパラメータ名
   └─ switch → 0/1変換

4. クエリ実行
   └─ Invoke-DbaQuery -CommandType "StoredProcedure"でsp_WhoIsActive呼び出し

5. エラーハンドリング
   ├─ "Could not find"エラー → Install-DbaWhoIsActive案内
   └─ その他のエラー → "Invalid query"メッセージ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータフィルタリング]
    B --> C{インスタンスループ}
    C -->|次のInstance| D[Connect-DbaInstance<br/>MinimumVersion=9]
    D --> E{接続成功?}
    E -->|No| F[エラー出力]
    F --> C
    E -->|Yes| G[パラメータマッピング構築]
    G --> H[Invoke-DbaQuery<br/>CommandType=StoredProcedure]
    H --> I{実行成功?}
    I -->|No| J{sp_WhoIsActive<br/>未インストール?}
    J -->|Yes| K[Install-DbaWhoIsActive案内]
    J -->|No| L[Invalid query エラー]
    I -->|Yes| M[結果出力]
    K --> C
    L --> C
    M --> C
    C -->|完了| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-175-01 | 最小バージョン | SQL Server 2005以上が必要 | 常時 |
| BR-175-02 | デフォルトデータベース | sp_WhoIsActiveはデフォルトでmasterに存在を期待 | Database未指定時 |
| BR-175-03 | 大文字小文字変換 | FilterType/NotFilterTypeは小文字に変換 | パラメータ使用時 |
| BR-175-04 | Switch変換 | switchパラメータは0/1に変換 | sp_WhoIsActive呼び出し時 |

### 計算ロジック

パラメータマッピング:
```powershell
$paramDictionary = @{
    Filter             = '@filter'
    FilterType         = '@filter_type'
    ShowOwnSpid        = '@show_own_spid'
    GetPlans           = '@get_plans'
    FindBlockLeaders   = '@find_block_leaders'
    # ... その他のマッピング
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| sp_WhoIsActive実行 | DMV各種 | SELECT | 読み取り専用 |
| DestinationTable出力 | 指定テーブル | INSERT | 結果保存 |

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

sp_WhoIsActiveは読み取り専用でDMVをクエリする。DestinationTable指定時のみ書き込みが発生。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンスへの接続失敗 | 接続情報を確認 |
| - | NotFound | sp_WhoIsActiveが見つからない | Install-DbaWhoIsActiveを実行 |
| - | QueryError | 無効なパラメータ/クエリ | パラメータを確認 |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時はStop-Functionで処理を中断。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- GetPlans=2で全体プラン取得時はメモリ使用量が増加
- DeltaIntervalで指定秒数の待機が発生
- 大規模環境では結果セットが大きくなる可能性

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

- VIEW SERVER STATE権限が必要
- SqlCredentialによる安全な認証をサポート
- sp_WhoIsActiveへのEXECUTE権限が必要

## 備考

- Adam Machanicの許可を得て実装
- 詳細: http://whoisactive.com
- 寄付: http://tinyurl.com/WhoIsActiveDonate

---

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

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

### 推奨読解順序

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

パラメータ構造とsp_WhoIsActiveへのマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 270-295行目: パラメータ辞書マッピング |

**読解のコツ**: PowerShellパラメータ名がsp_WhoIsActiveのどのパラメータに対応するか理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 関数全体の流れを把握 |

**主要処理フロー**:
1. **253-259行目**: beginブロックでパラメータ準備
2. **261-268行目**: インスタンス接続（MinimumVersion=9）
3. **270-295行目**: パラメータ辞書定義
4. **298-312行目**: パラメータ値のSQL用変換
5. **313行目**: Invoke-DbaQuery呼び出し

#### Step 3: エラーハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 314-320行目: エラー処理 |

**主要処理フロー**:
- **315-316行目**: "Could not find"でsp_WhoIsActive未インストール判定
- **317-318行目**: その他のエラーは"Invalid query"として処理

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

```
Invoke-DbaWhoIsActive
    │
    ├─ beginブロック
    │      └─ パラメータフィルタリング
    │
    └─ processブロック
           ├─ Connect-DbaInstance (MinimumVersion=9)
           │
           ├─ パラメータマッピング構築
           │      └─ switch → 0/1変換
           │
           └─ Invoke-DbaQuery
                  └─ sp_WhoIsActive (StoredProcedure)
```

### データフロー図

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

SqlInstance ──────────▶ Connect-DbaInstance
                              │
パラメータ群 ─────────▶ パラメータマッピング ─▶ $sqlParameter
                              │
                              ▼
                       Invoke-DbaQuery
                              │
                              ▼
                       sp_WhoIsActive
                              │
                              ▼
                     ┌────────┴────────┐
                     ▼                 ▼
               DataRow[]          PSObject[]
                     │                 │
                     └────────┬────────┘
                              ▼
                        パイプライン出力
                              │
                              ▼
                     DestinationTable (オプション)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | ソース | メイン関数 |
| Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | ソース | sp_WhoIsActiveインストール |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
