# 機能設計書 6-sp_BlitzWho

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzWhoストアドプロシージャの機能設計について記載する。sp_BlitzWhoは現在実行中のクエリをsp_whoより詳細に表示する診断ツールである。

### 本機能の処理概要

sp_BlitzWhoは、SQL Serverで現在実行中のクエリをリアルタイムで詳細表示するストアドプロシージャである。メモリ付与、並列度、実行プラン、待機情報など、sp_whoやsp_who2では取得できない詳細情報を提供する。

**業務上の目的・背景**：SQL Server標準のsp_whoやsp_who2は基本的な情報のみを表示し、パフォーマンス問題の診断には不十分である。sp_BlitzWhoは、実行中クエリの詳細な実行統計、メモリ使用状況、並列度、待機状態など、問題診断に必要な包括的な情報を一度に取得できる。

**機能の利用シーン**：
- パフォーマンス問題発生時のリアルタイム診断
- 長時間実行クエリの特定
- ブロッキングチェーンの確認
- メモリ付与問題の診断
- sp_BlitzFirstからの呼び出し

**主要な処理内容**：
1. sys.dm_exec_requestsから実行中リクエスト取得
2. sys.dm_exec_sessionsからセッション情報取得
3. クエリテキストと実行プランの取得
4. メモリ付与情報の取得
5. 待機統計の取得

**関連システム・外部連携**：
- sp_BlitzFirst: サンプリング開始・終了時に呼び出される
- 各種DMV（dm_exec_requests、dm_exec_sessions等）

**権限による制御**：
- VIEW SERVER STATE権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | sp_BlitzWho 結果画面 | 主機能 | 現在実行中のクエリをリアルタイムで詳細表示（メモリグラント、並列度、実行プラン含む） |
| 4 | sp_BlitzFirst 診断結果画面 | 補助機能 | サンプリング開始時と終了時にsp_BlitzWhoを呼び出し、実行中クエリを取得 |
| 5 | sp_BlitzFirst 詳細統計画面（ExpertMode） | 補助機能 | ExpertModeでも開始時と終了時にsp_BlitzWhoを呼び出し |
| 12 | sp_BlitzAnalysis 結果画面 | API連携 | BlitzWhoテーブルから過去の実行中クエリ情報を取得 |

## 機能種別

リアルタイム診断 / クエリ監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| @Help | TINYINT | No | ヘルプ表示 | デフォルト0 |
| @ShowSleepingSPIDs | TINYINT | No | スリープSPIDを表示 | デフォルト0 |
| @ExpertMode | BIT | No | 詳細モード | デフォルト0 |
| @Debug | BIT | No | デバッグモード | デフォルト0 |
| @OutputDatabaseName | NVARCHAR(256) | No | 出力先データベース | NULL許可 |
| @OutputSchemaName | NVARCHAR(256) | No | 出力先スキーマ | NULL許可 |
| @OutputTableName | NVARCHAR(256) | No | 出力先テーブル | NULL許可 |
| @OutputTableRetentionDays | TINYINT | No | テーブル保持日数 | デフォルト3 |
| @MinElapsedSeconds | INT | No | 最小経過時間フィルタ | デフォルト0 |
| @MinCPUTime | INT | No | 最小CPU時間フィルタ | デフォルト0 |
| @MinLogicalReads | INT | No | 最小論理読み取りフィルタ | デフォルト0 |
| @MinPhysicalReads | INT | No | 最小物理読み取りフィルタ | デフォルト0 |
| @MinWrites | INT | No | 最小書き込みフィルタ | デフォルト0 |
| @MinTempdbMB | INT | No | 最小TempDB使用量フィルタ | デフォルト0 |
| @MinRequestedMemoryKB | INT | No | 最小要求メモリフィルタ | デフォルト0 |
| @MinBlockingSeconds | INT | No | 最小ブロッキング時間フィルタ | デフォルト0 |
| @CheckDateOverride | DATETIMEOFFSET | No | 日時オーバーライド | NULL許可 |
| @ShowActualParameters | BIT | No | 実パラメータ表示 | デフォルト0 |
| @GetOuterCommand | BIT | No | 外部コマンド取得 | デフォルト0 |
| @GetLiveQueryPlan | BIT | No | ライブクエリプラン取得 | NULL時は自動 |
| @SortOrder | NVARCHAR(256) | No | ソート順序 | デフォルトelapsed time |
| @Version | VARCHAR(30) | No | バージョン（OUTPUT） | 出力専用 |
| @VersionDate | DATETIME | No | バージョン日付（OUTPUT） | 出力専用 |

### 入力データソース

- sys.dm_exec_requests: 実行中リクエスト
- sys.dm_exec_sessions: セッション情報
- sys.dm_exec_sql_text: SQLテキスト
- sys.dm_exec_query_plan: クエリプラン
- sys.dm_exec_query_memory_grants: メモリ付与
- sys.dm_exec_session_wait_stats: セッション待機統計

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| elapsed_time | varchar(41) | 経過時間 |
| session_id | smallint | セッションID |
| database_name | nvarchar(128) | データベース名 |
| query_text | nvarchar(max) | クエリテキスト |
| outer_command | nvarchar(4000) | 外部コマンド |
| query_plan | xml | クエリプラン |
| live_query_plan | xml | ライブクエリプラン |
| query_cost | float | クエリコスト |
| status | nvarchar(30) | ステータス |
| wait_info | nvarchar(max) | 待機情報 |
| wait_resource | nvarchar(max) | 待機リソース |
| blocking_session_id | smallint | ブロッキングセッションID |
| open_transaction_count | int | オープントランザクション数 |
| request_cpu_time | int | リクエストCPU時間 |
| request_logical_reads | bigint | リクエスト論理読み取り |
| tempdb_allocations_mb | decimal(38,2) | TempDB割り当て(MB) |
| degree_of_parallelism | smallint | 並列度 |
| requested_memory_kb | bigint | 要求メモリ(KB) |
| grant_memory_kb | bigint | 付与メモリ(KB) |

### 出力先

- 画面表示（デフォルト）
- 指定テーブルへの出力（@OutputTableName指定時）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証と初期化
   └─ 出力先、フィルタ条件の設定

2. 出力テーブル準備（指定時）
   └─ テーブル作成または既存テーブル確認

3. 実行中クエリ情報取得
   └─ dm_exec_requests等からの情報取得

4. フィルタリング
   └─ 各種Min*パラメータによるフィルタ

5. 結果出力
   └─ ソート順序に従って結果セット返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ出力]
    C --> Z[終了]
    B -->|No| D[パラメータ初期化]
    D --> E{@OutputTableName指定?}
    E -->|Yes| F[出力テーブル準備]
    E -->|No| G[クエリ情報取得]
    F --> G
    G --> H[フィルタリング]
    H --> I[ソート]
    I --> J{テーブル出力?}
    J -->|Yes| K[テーブルINSERT]
    J -->|No| L[結果セット出力]
    K --> Z
    L --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | テーブル出力時ExpertMode | テーブル出力時は@ExpertMode=1に強制 | @OutputTableName指定時 |
| BR-002 | ライブプラン自動設定 | SQL Server 2016以降はデフォルトで有効 | @GetLiveQueryPlan=NULL |
| BR-003 | 保持期間 | 指定日数以上古いデータを自動削除 | @OutputTableRetentionDays |
| BR-004 | ソート順序 | elapsed_time, cpu, reads等でソート可能 | @SortOrder |
| BR-005 | スリープSPID | @ShowSleepingSPIDs=0でスリープSPIDを除外 | デフォルト |

### 計算ロジック

**TempDB使用量計算**:
```sql
tempdb_allocations_mb = (user_objects_alloc_page_count + internal_objects_alloc_page_count) * 8 / 1024.0
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 参照 | sys.dm_exec_requests | SELECT | 実行中リクエスト取得 |
| 参照 | sys.dm_exec_sessions | SELECT | セッション情報取得 |
| 参照 | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |
| 参照 | sys.dm_exec_query_plan | SELECT | クエリプラン取得 |
| 参照 | sys.dm_exec_query_memory_grants | SELECT | メモリ付与情報取得 |
| 挿入 | BlitzWho | INSERT | 結果出力（オプション） |
| 削除 | BlitzWho | DELETE | 古いデータ削除 |

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

#### BlitzWho（出力テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | session_id, query_text, query_plan等 | 実行中クエリ情報 | @OutputTableName指定時 |
| DELETE | - | CheckDate < @OutputTableCleanupDate | 保持期間超過データ削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 出力パラメータエラー | @OutputTableNameのみ指定 | エラーなし、Azure SQL DBは自動補完 |

### リトライ仕様

特定のリトライ機能は実装されていない。

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

READ UNCOMMITTED分離レベルで実行される。

## パフォーマンス要件

- 通常実行: 数秒以内
- @GetLiveQueryPlan=1: 若干のオーバーヘッド

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

- VIEW SERVER STATE権限が必要
- クエリテキストにはセンシティブ情報が含まれる可能性

## 備考

- バージョン: 8.29（2026年2月3日時点）
- テーブル出力はSQL Server 2012以降対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | **180-277行目**: 出力テーブル定義（CREATE TABLE文） |

**読解のコツ**: 出力テーブルのカラム定義が実際の出力仕様を示している。JoinKey計算列に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | **5-30行目**: ALTER PROCEDURE定義とパラメータ |
| 2-2 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | **31-41行目**: 初期設定とバージョンチェック |

**主要処理フロー**:
1. **32-34行目**: SET NOCOUNT ON、STATISTICS XML OFF、READ UNCOMMITTED設定
2. **36行目**: バージョン情報設定
3. **88-134行目**: バージョン・プラットフォーム検出

#### Step 3: 出力テーブル処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzWho.sql | `sp_BlitzWho.sql` | **158-334行目**: 出力テーブル作成と古いデータ削除 |

**主要処理フロー**:
- **162-163行目**: @ExpertMode=1への強制設定
- **166-283行目**: テーブル作成SQL（IF NOT EXISTS）
- **316-333行目**: 古いデータ削除処理

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

```
sp_BlitzWho
    │
    ├─ sys.dm_exec_requests (実行中リクエスト)
    │
    ├─ sys.dm_exec_sessions (セッション)
    │
    ├─ sys.dm_exec_sql_text (SQLテキスト)
    │
    ├─ sys.dm_exec_query_plan (クエリプラン)
    │
    ├─ sys.dm_exec_query_memory_grants (メモリ付与)
    │
    ├─ sys.dm_exec_session_wait_stats (待機統計)
    │
    └─ 出力テーブル (オプション)
```

### データフロー図

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

パラメータ ──────────────────▶ パラメータ検証 ─────────────────▶ 結果セット
   │                              │                                   │
dm_exec_requests ────────────▶ リクエスト情報取得 ──────────────▶ │
   │                              │                                   │
dm_exec_sessions ────────────▶ セッション情報取得 ──────────────▶ │
   │                              │                                   │
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を呼び出し |
| sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 関連 | BlitzWhoテーブルからデータ取得 |
