# 画面設計書 170-Who Is Active

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWho Is Active機能（Install-DbaWhoIsActive、Invoke-DbaWhoIsActive）の画面設計書です。Adam MachanicのSQL Serverセッション監視ストアドプロシージャsp_WhoIsActiveのインストールと実行を提供します。

### 本画面の処理概要

**業務上の目的・背景**：sp_WhoIsActiveは、SQL Serverのアクティブセッションをリアルタイムで監視するための最も広く使用されているツールです。実行中のクエリ、ブロッキングチェーン、待機統計、リソース消費に関する詳細情報を、SQL Server Profilerのオーバーヘッドなく提供します。本機能は、このストアドプロシージャのインストールと実行を自動化します。

**画面へのアクセス方法**：PowerShellコマンドラインから `Install-DbaWhoIsActive` でインストールし、`Invoke-DbaWhoIsActive` で実行します。

**主要な操作・処理内容**：
1. GitHubから最新のsp_WhoIsActiveをダウンロードまたはローカルファイルを使用
2. 指定データベース（推奨: master）にストアドプロシージャをインストール
3. sp_WhoIsActiveを実行してアクティブセッション情報を取得
4. 実行プラン、ロック情報、トランザクション情報などの詳細オプションを提供

**画面遷移**：Install-DbaWhoIsActiveでインストール後、Invoke-DbaWhoIsActiveで繰り返し実行可能です。

**権限による表示制御**：sysadmin権限推奨です。sp_WhoIsActiveはVIEW SERVER STATE権限で動作しますが、一部の機能は制限されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 218 | Install-DbaWhoIsActive | 主機能 | sp_WhoIsActiveのインストール |
| 219 | Invoke-DbaWhoIsActive | 主機能 | sp_WhoIsActiveの実行 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |
| 447 | Save-DbaCommunitySoftware | 内部呼出 | sp_WhoIsActiveのダウンロード |

## 画面種別

CLI（コマンドラインインターフェース）- インストール・監視

## URL/ルーティング

PowerShellコマンド:
- `Install-DbaWhoIsActive`
- `Invoke-DbaWhoIsActive`

## 入出力項目

### Install-DbaWhoIsActive 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | インストール先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Database | object | No | インストール先データベース（デフォルト: master） |
| LocalFile | string | No | ローカルのsp_WhoIsActiveファイルパス |
| Force | switch | No | キャッシュを無視して再ダウンロード |
| EnableException | switch | No | 例外を有効化 |

### Install-DbaWhoIsActive 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | インストール先データベース |
| Name | string | ストアドプロシージャ名（sp_WhoisActive） |
| Version | string | sp_WhoIsActiveのバージョン |
| Status | string | Installed（新規）またはUpdated（更新） |

### Invoke-DbaWhoIsActive 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 実行先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Database | string | No | sp_WhoIsActiveがインストールされているDB |
| Filter | string | No | セッションフィルタ（ワイルドカード対応） |
| FilterType | string | No | フィルタタイプ（Session/Program/Database/Login/Host） |
| NotFilter | string | No | 除外フィルタ |
| NotFilterType | string | No | 除外フィルタタイプ |
| ShowOwnSpid | switch | No | 自身のセッションを含める |
| ShowSystemSpids | switch | No | システムセッションを含める |
| ShowSleepingSpids | int | No | スリープセッションの表示（0/1/2） |
| GetFullInnerText | switch | No | 完全なバッチテキストを取得 |
| GetPlans | int | No | 実行プランを取得（1/2） |
| GetOuterCommand | switch | No | 外部コマンドを取得 |
| GetTransactionInfo | switch | No | トランザクション情報を取得 |
| GetTaskInfo | int | No | タスク情報を取得（0/1/2） |
| GetLocks | switch | No | ロック情報を取得 |
| GetAverageTime | switch | No | 平均実行時間を取得 |
| GetAdditonalInfo | switch | No | 追加情報を取得 |
| FindBlockLeaders | switch | No | ブロッキングリーダーを特定 |
| DeltaInterval | int | No | デルタ間隔（秒） |
| OutputColumnList | string | No | 出力カラムリスト |
| SortOrder | string | No | ソート順 |
| FormatOutput | int | No | 出力フォーマット（0/1/2） |
| DestinationTable | string | No | 結果の保存先テーブル |
| ReturnSchema | switch | No | スキーマのみ返却 |
| Schema | string | No | スキーマ返却（別名） |
| Help | switch | No | ヘルプを表示 |
| As | string | No | 出力形式（DataSet/DataTable/DataRow/PSObject） |
| EnableException | switch | No | 例外を有効化 |

### Invoke-DbaWhoIsActive 出力項目（基本）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 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有効時） |
| wait_info | string | 待機情報（GetTaskInfo有効時） |

## 表示項目

出力形式はAsパラメータで指定可能（DataRow/DataTable/DataSet/PSObject）。デフォルトはDataRowです。

## イベント仕様

### Install-DbaWhoIsActive

1. **ソフトウェア取得**（行126-134）: Save-DbaCommunitySoftwareでダウンロードまたはキャッシュ使用
2. **SQLファイル読み込み**（行136-156）: sp_WhoIsActive.sqlを読み込み
3. **SQL Server接続**（行163-167）: Connect-DbaInstanceで接続
4. **DB選択**（行169-182）: データベース選択（GUIまたはパラメータ）
5. **インストール実行**（行183-220）: Invoke-DbaQueryでプロシージャ作成

### Invoke-DbaWhoIsActive

1. **パラメータ準備**（行253-260）: フィルタタイプを小文字に変換
2. **SQL Server接続**（行264-268）: Connect-DbaInstance -MinimumVersion 9で接続
3. **パラメータマッピング**（行270-295）: PowerShellパラメータをsp_WhoIsActiveパラメータにマッピング
4. **プロシージャ実行**（行298-313）: Invoke-DbaQueryでsp_WhoIsActive実行

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Install | sys.procedures | INSERT/UPDATE | sp_WhoIsActiveの作成/更新 |
| Invoke | 各種DMV | SELECT | セッション情報取得 |
| DestinationTable指定時 | 指定テーブル | INSERT | 結果の永続化 |

### Install時の確認クエリ

```sql
SELECT COUNT(*) [proc_count]
FROM sys.procedures
WHERE is_ms_shipped = 0
  AND name LIKE '%sp_WhoisActive%'
```

## メッセージ仕様

### Install-DbaWhoIsActive

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 接続失敗 | "Failure" - ConnectionError |
| Error | キャッシュ更新失敗 | "Failed to update local cached copy" |
| Error | インストール失敗 | "Failed to install stored procedure." |
| Error | DB未発見 | "Failed to find database {Database} on {instance}" |
| Warning | master以外選択 | "You have selected a database other than master..." |

### Invoke-DbaWhoIsActive

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 接続失敗 | "Failure" - ConnectionError |
| Error | プロシージャ未発見 | "sp_whoisactive not found, please install using Install-DbaWhoIsActive." |
| Error | クエリ失敗 | "Invalid query." |
| Verbose | 実行中 | "Collecting sp_whoisactive data from server: {instance}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| sp_WhoIsActive未インストール | Install-DbaWhoIsActiveでのインストールを案内 |
| データベース未発見 | Stop-Functionでエラーを記録 |
| ダウンロード失敗 | Stop-Functionでエラーを記録 |

## 備考

- sp_WhoIsActiveはAdam Machanicが開発・保守
- 参考: http://whoisactive.com
- 寄付: http://tinyurl.com/WhoIsActiveDonate
- master以外のデータベースにインストール時は、Invoke-DbaWhoIsActiveで-Databaseパラメータが必要
- SQL Server 2005以上が必要（-MinimumVersion 9）
- -ForceでGitHubから最新版を強制ダウンロード可能
- ローカルファイル（.sqlまたは.zip）からもインストール可能

---

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

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

### 推奨読解順序

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

Install-DbaWhoIsActiveとInvoke-DbaWhoIsActiveの出力構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | 行65-78の.OUTPUTSセクション |
| 1-2 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 行145-172の.OUTPUTSセクション |

**読解のコツ**: Install-DbaWhoIsActiveはインストール結果を返し、Invoke-DbaWhoIsActiveはsp_WhoIsActiveの実行結果を返す点に注目。

#### Step 2: Install-DbaWhoIsActiveを理解する

ストアドプロシージャのダウンロードとインストールを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | 行108-118のパラメータ定義 |
| 2-2 | Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | 行120-157のbeginブロック（ダウンロード・読み込み） |
| 2-3 | Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | 行183-221のインストール処理 |

**主要処理フロー**:
1. **行126-134**: Save-DbaCommunitySoftwareでダウンロードまたはキャッシュ使用
2. **行144-145**: SQLファイルの読み込みと"USE master"の除去
3. **行147-155**: バージョン文字列の抽出
4. **行188**: sys.proceduresでの既存確認
5. **行191**: Invoke-DbaQueryでプロシージャ作成

#### Step 3: Invoke-DbaWhoIsActiveを理解する

sp_WhoIsActiveの実行とパラメータマッピングを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 行207-252のパラメータ定義 |
| 3-2 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 行270-295のパラメータマッピング |
| 3-3 | Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | 行298-320のプロシージャ実行 |

**主要処理フロー**:
- **行258-259**: FilterType/NotFilterTypeを小文字に変換（大文字小文字区別DB対応）
- **行265**: Connect-DbaInstance -MinimumVersion 9で接続
- **行270-295**: PowerShellパラメータからsp_WhoIsActiveパラメータへのマッピング
- **行313**: Invoke-DbaQuery -CommandType "StoredProcedure"で実行

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

```
Install-DbaWhoIsActive
    |
    +-- [beginブロック] 初期化 (行120-157)
    |       |
    |       +-- Save-DbaCommunitySoftware (行129)
    |       |       └── GitHubからダウンロードまたはキャッシュ
    |       |
    |       +-- Get-ChildItem (行137-141)
    |       |       └── sp_WhoIsActive.sqlの検索
    |       |
    |       └── [IO.File]::ReadAllText (行144)
    |               └── SQLスクリプト読み込み
    |
    +-- Connect-DbaInstance (行164)
    |       └── SQL Serverへの接続
    |
    +-- [Database未指定時]
    |       └── Show-DbaDbList (行171)
    |               └── GUI選択ダイアログ
    |
    +-- $server.Query() (行188)
    |       └── 既存プロシージャ確認
    |
    +-- Invoke-DbaQuery (行191)
    |       └── プロシージャ作成/更新
    |
    └── PSCustomObject出力 (行203-211)
            └── インストール結果

Invoke-DbaWhoIsActive
    |
    +-- [beginブロック] パラメータ準備 (行253-260)
    |       └── FilterType/NotFilterTypeの小文字変換
    |
    +-- Connect-DbaInstance -MinimumVersion 9 (行265)
    |       └── SQL Serverへの接続
    |
    +-- パラメータマッピング (行270-295)
    |       └── PowerShell → sp_WhoIsActiveパラメータ変換
    |
    +-- Invoke-DbaQuery (行313)
    |       └── sp_WhoIsActive実行
    |
    └── エラーハンドリング (行315-319)
            └── 未インストール時の案内
```

### データフロー図

```
[Install-DbaWhoIsActive]

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

SqlInstance ─────────────────┐
                             │
SqlCredential ───────────────┼──> Connect-DbaInstance
                             │          │
LocalFile ───────────────────┼──> Save-DbaCommunitySoftware
Force ───────────────────────┘   (ダウンロード/キャッシュ)
                                        │
                                        v
                                [IO.File]::ReadAllText
                                (SQLスクリプト読み込み)
                                        │
Database ────────────────────────> Show-DbaDbList (GUIまたはパラメータ)
                                        │
                                        v
                                $server.Query()
                                (既存確認)
                                        │
                                        v
                                Invoke-DbaQuery
                                (CREATE/ALTER PROCEDURE)
                                        │
                                        v
                                PSCustomObject
                                (インストール結果)


[Invoke-DbaWhoIsActive]

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

SqlInstance ─────────────────┐
                             │
SqlCredential ───────────────┼──> Connect-DbaInstance
Database ────────────────────┘   -MinimumVersion 9
                                        │
                                        v
Filter ──────────────────────┐
FilterType ──────────────────┤
NotFilter ───────────────────┤   パラメータマッピング
NotFilterType ───────────────┤   (paramDictionary)
GetPlans ────────────────────┤          │
GetLocks ────────────────────┤          v
GetTransactionInfo ──────────┤
FindBlockLeaders ────────────┤   Invoke-DbaQuery
DeltaInterval ───────────────┤   -CommandType "StoredProcedure"
OutputColumnList ────────────┤          │
SortOrder ───────────────────┘          v

As ─────────────────────────────> DataRow/DataTable/DataSet/PSObject
                                 (sp_WhoIsActive結果)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaWhoIsActive.ps1 | `public/Install-DbaWhoIsActive.ps1` | ソース | sp_WhoIsActiveのインストール |
| Invoke-DbaWhoIsActive.ps1 | `public/Invoke-DbaWhoIsActive.ps1` | ソース | sp_WhoIsActiveの実行 |
| Save-DbaCommunitySoftware.ps1 | `internal/Save-DbaCommunitySoftware.ps1` | 内部関数 | コミュニティソフトウェアのダウンロード |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | SQLクエリ実行 |
| Show-DbaDbList.ps1 | `internal/Show-DbaDbList.ps1` | 内部関数 | データベース選択GUI |
