# 帳票設計書 5-sp_BlitzWho

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzWhoストアドプロシージャが出力する実行中クエリ分析帳票の設計を記述する。

### 本帳票の処理概要

sp_BlitzWhoは、現在実行中のすべてのクエリのスナップショットを詳細に出力するストアドプロシージャである。各セッションのクエリテキスト、実行プラン、メモリグラント、待機情報、ブロッキング状態など、実行中クエリに関する包括的な情報を単一の結果セットで提供する。

**業務上の目的・背景**：SQL Serverで「今何が実行されているか」を把握することは、パフォーマンス問題の診断やリソース使用状況の監視に不可欠である。本帳票は、DBAやオペレーターが実行中のクエリを一覧で確認し、問題のあるクエリを迅速に特定することを目的としている。sp_who2の高機能版として設計されている。

**帳票の利用シーン**：
- パフォーマンス問題発生時の実行中クエリ確認
- ブロッキングチェーンの特定
- メモリグラント使用状況の監視
- 長時間実行クエリの検出
- sp_BlitzFirstからの自動呼び出し

**主要な出力内容**：
1. session_id（セッションID）：実行中のセッション識別子
2. elapsed_time（経過時間）：クエリの実行時間
3. query_text（クエリテキスト）：実行中のSQL文
4. query_plan（実行プラン）：XML形式の実行プラン
5. wait_info（待機情報）：現在の待機状態
6. blocking_session_id（ブロッキングセッション）：ブロック元
7. memory_grant（メモリグラント）：割り当てメモリ
8. tempdb_allocations_mb（tempdb使用量）：一時領域使用量

**帳票の出力タイミング**：
- ストアドプロシージャ `EXEC sp_BlitzWho` の手動実行時
- sp_BlitzFirstからの自動呼び出し時
- SQL Server Agentジョブによる定期実行時

**帳票の利用者**：
- データベース管理者（DBA）
- システムオペレーター
- パフォーマンスエンジニア
- アプリケーションサポート担当者

## 帳票種別

実行中クエリスナップショット / セッション一覧表

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | SQL Server Management Studio | N/A | `EXEC sp_BlitzWho` 実行 |
| N/A | Azure Data Studio | N/A | `EXEC sp_BlitzWho` 実行 |
| N/A | コマンドライン | sqlcmd | スクリプト実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 結果セット / テーブル書き込み |
| 用紙サイズ | N/A（結果セットとして出力） |
| 向き | N/A |
| ファイル名 | N/A（テーブル出力時は@OutputTableName指定） |
| 出力方法 | 結果セット返却 / テーブル書き込み |
| 文字コード | NVARCHAR（Unicode） |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット: 実行中クエリ一覧                                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  session_id | elapsed_time | database_name | query_text | wait_info | ...   │
│  ---------- | ------------ | ------------- | ---------- | --------- | ...   │
│     55      | 00:00:05.123 | UserDB        | SELECT ... | PAGEIO... | ...   │
│     72      | 00:01:23.456 | ReportDB      | UPDATE ... | LCK_M_X   | ...   │
│    ...      | ...          | ...           | ...        | ...       | ...   │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 出力カラム詳細

| No | 項目名 | 説明 | データ型 | 表示形式 |
|----|-------|------|----------|---------|
| 1 | elapsed_time | 経過時間 | VARCHAR(41) | HH:MM:SS.mmm |
| 2 | session_id | セッションID | SMALLINT | 数値 |
| 3 | database_name | データベース名 | NVARCHAR(128) | テキスト |
| 4 | query_text | クエリテキスト | NVARCHAR(MAX) | テキスト |
| 5 | outer_command | 外部コマンド | NVARCHAR(4000) | テキスト |
| 6 | query_plan | 実行プラン | XML | XML |
| 7 | live_query_plan | ライブ実行プラン | XML | XML |
| 8 | cached_parameter_info | キャッシュパラメータ | NVARCHAR(MAX) | テキスト |
| 9 | live_parameter_info | ライブパラメータ | NVARCHAR(MAX) | テキスト |
| 10 | query_cost | クエリコスト | FLOAT | 数値 |
| 11 | status | ステータス | NVARCHAR(30) | テキスト |
| 12 | wait_info | 待機情報 | NVARCHAR(MAX) | テキスト |
| 13 | wait_resource | 待機リソース | NVARCHAR(MAX) | テキスト |
| 14 | top_session_waits | トップセッション待機 | NVARCHAR(MAX) | テキスト |
| 15 | blocking_session_id | ブロッキングセッション | SMALLINT | 数値 |
| 16 | open_transaction_count | オープントランザクション数 | INT | 数値 |
| 17 | host_name | ホスト名 | NVARCHAR(128) | テキスト |
| 18 | login_name | ログイン名 | NVARCHAR(128) | テキスト |
| 19 | program_name | プログラム名 | NVARCHAR(128) | テキスト |
| 20 | request_cpu_time | リクエストCPU時間 | INT | ミリ秒 |
| 21 | request_logical_reads | 論理読み取り | BIGINT | 数値 |
| 22 | request_writes | 書き込み | BIGINT | 数値 |
| 23 | tempdb_allocations_mb | tempdb割当（MB） | DECIMAL(38,2) | 数値 |
| 24 | requested_memory_kb | 要求メモリ（KB） | BIGINT | 数値 |
| 25 | grant_memory_kb | 付与メモリ（KB） | BIGINT | 数値 |
| 26 | degree_of_parallelism | 並列度 | SMALLINT | 数値 |

## 出力条件

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @Help | TINYINT | 0 | 1でヘルプ表示 |
| @ShowSleepingSPIDs | TINYINT | 0 | スリープ中のSPIDを表示 |
| @ExpertMode | BIT | 0 | 詳細モード |
| @Debug | BIT | 0 | デバッグモード |
| @OutputDatabaseName | NVARCHAR(256) | NULL | 出力先DB名 |
| @OutputSchemaName | NVARCHAR(256) | NULL | 出力先スキーマ名 |
| @OutputTableName | NVARCHAR(256) | NULL | 出力先テーブル名 |
| @OutputTableRetentionDays | TINYINT | 3 | データ保持日数 |
| @MinElapsedSeconds | INT | 0 | 最小経過時間フィルタ |
| @MinCPUTime | INT | 0 | 最小CPU時間フィルタ |
| @MinLogicalReads | INT | 0 | 最小論理読み取りフィルタ |
| @MinPhysicalReads | INT | 0 | 最小物理読み取りフィルタ |
| @MinWrites | INT | 0 | 最小書き込みフィルタ |
| @MinTempdbMB | INT | 0 | 最小tempdb使用量フィルタ |
| @MinRequestedMemoryKB | INT | 0 | 最小要求メモリフィルタ |
| @MinBlockingSeconds | INT | 0 | 最小ブロッキング時間フィルタ |
| @ShowActualParameters | BIT | 0 | 実際のパラメータ値を表示 |
| @GetOuterCommand | BIT | 0 | 外部コマンドを取得 |
| @GetLiveQueryPlan | BIT | NULL | ライブプラン取得（NULLで自動） |
| @SortOrder | NVARCHAR(256) | 'elapsed time' | ソート順 |

### ソート順オプション

| SortOrder | 説明 |
|-----------|------|
| elapsed time | 経過時間（デフォルト） |
| cpu | CPU時間 |
| reads | 論理読み取り |
| writes | 書き込み |
| blocking | ブロッキング時間 |
| memory | メモリグラント |
| tempdb | tempdb使用量 |

### 改ページ条件

結果セットのため改ページなし。

## データベース参照仕様

### 参照DMV一覧

| DMV名 | 用途 | 結合条件 |
|-------|------|---------|
| sys.dm_exec_requests | 実行中リクエスト | session_id |
| sys.dm_exec_sessions | セッション情報 | session_id |
| sys.dm_exec_connections | 接続情報 | session_id |
| sys.dm_exec_sql_text | SQLテキスト | sql_handle |
| sys.dm_exec_query_plan | 実行プラン | plan_handle |
| sys.dm_exec_query_statistics_xml | ライブプラン | session_id |
| sys.dm_exec_session_wait_stats | セッション待機統計 | session_id |
| sys.dm_exec_query_memory_grants | メモリグラント | session_id |
| sys.dm_resource_governor_workload_groups | リソースガバナー | group_id |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| elapsed_time | DATEDIFF(ms, start_time, GETDATE()) | フォーマット変換 | HH:MM:SS.mmm形式 |
| tempdb_allocations_mb | (user_objects_alloc_page_count + internal_objects_alloc_page_count) * 8 / 1024 | 小数点以下2桁 | |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[sp_BlitzWho実行] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ表示して終了]
    B -->|No| D{出力テーブル指定?}
    D -->|Yes| E[テーブル存在確認/作成]
    E --> F[古いデータ削除]
    D -->|No| G[クエリ構築]
    F --> G
    G --> H[dm_exec_requests結合]
    H --> I[dm_exec_sessions結合]
    I --> J[待機情報取得]
    J --> K[メモリグラント取得]
    K --> L{@GetLiveQueryPlan?}
    L -->|Yes| M[ライブプラン取得]
    L -->|No| N[キャッシュプラン取得]
    M --> O[フィルター適用]
    N --> O
    O --> P{出力テーブル指定?}
    P -->|Yes| Q[テーブルに挿入]
    P -->|No| R[結果セット返却]
    Q --> S[終了]
    R --> S
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力パラメータ不足 | @OutputTableName指定時にDB/Schema未指定 | 必須パラメータエラー | DB/Schema名を指定 |
| バージョン制限 | SQL Server 2012未満でテーブル出力 | Outputting to table is only supported with SQL Server 2012 and higher | バージョンアップグレード |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | アクティブセッション数（通常10-1000） |
| 目標出力時間 | 5秒以内 |
| 同時出力数上限 | 制限なし |

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

- VIEW SERVER STATE権限が必要
- クエリテキストには機密情報が含まれる可能性あり
- ログイン名、ホスト名等の接続情報が出力される
- 出力テーブルへのアクセス制御が必要

## 備考

- バージョン: 8.29（2026年2月3日リリース）
- ライセンス: MIT License
- 公式サイト: http://FirstResponderKit.org
- sp_BlitzFirstから呼び出される
- Azure SQL Database対応

---

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

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

### 推奨読解順序

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

まず、出力先テーブルの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | 行180-277: 出力テーブル作成SQL |

**読解のコツ**: 出力テーブルは動的に作成されるため、CREATE TABLE文を確認すること。

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

処理の起点となるストアドプロシージャのシグネチャとパラメータを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | 行5-30: ALTER PROCEDUREとパラメータ定義 |

**主要処理フロー**:
1. **行36**: バージョン情報の設定
2. **行45-85**: @Help=1の場合のヘルプ出力
3. **行88-134**: バージョンチェックと変数初期化

#### Step 3: 動的SQLの構築を理解する

メインクエリの構築ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | 行99-118: @SessionWaitsSQL変数定義 |

**主要処理フロー**:
- セッション待機情報の結合SQL
- ライブクエリプラン取得の分岐

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

```
sp_BlitzWho (エントリーポイント)
    │
    ├─ パラメータヘルプ表示 (@Help = 1)
    │
    ├─ 出力テーブル処理（@OutputTableName指定時）
    │      ├─ テーブル存在確認
    │      ├─ テーブル作成（未存在時）
    │      ├─ カラム追加（必要時）
    │      └─ 古いデータ削除
    │
    ├─ ビュー作成（_Deltas）
    │
    └─ メインクエリ実行
           ├─ sys.dm_exec_requests
           ├─ sys.dm_exec_sessions
           ├─ sys.dm_exec_connections
           ├─ sys.dm_exec_sql_text
           ├─ sys.dm_exec_query_plan
           ├─ sys.dm_exec_session_wait_stats（利用可能時）
           └─ sys.dm_exec_query_memory_grants
```

### データフロー図

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

パラメータ指定 ──────────▶ sp_BlitzWho ──────────▶ 結果セット
                               │                        │
dm_exec_requests ◀─────────────┤                        ├──▶ 出力テーブル
dm_exec_sessions ◀─────────────┤                        │
dm_exec_connections ◀──────────┤                        └──▶ _Deltasビュー
dm_exec_sql_text ◀─────────────┤
dm_exec_query_plan ◀───────────┤
dm_exec_query_memory_grants ◀──┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzWho.sql | `sp_BlitzWho.sql` | ソース | メインストアドプロシージャ |
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | sp_BlitzWhoを呼び出す |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | スクリプト | 全スクリプトのインストール |
