# 通知設計書 63-待機統計キャプチャ

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzFirstストアドプロシージャにおける「待機統計キャプチャ」通知（RAISERROR）の設計を定義する。

### 本通知の処理概要

この通知は、sp_BlitzFirstの実行時に待機統計（Wait Stats）、パフォーマンスカウンタ（Perfmon）、ファイル統計（File Stats）の第1パス（最初のスナップショット）をキャプチャするフェーズの開始を示す進捗情報メッセージである。

**業務上の目的・背景**：sp_BlitzFirstは、SQL Serverのパフォーマンス診断において「前後比較」方式を採用している。待機統計はSQL Serverがどのようなボトルネックで待機しているかを示す重要な指標であり、パフォーマンスカウンタはCPU、メモリ、I/Oなどのシステムリソースの使用状況を示す。ファイル統計はデータファイルとログファイルのI/Oパフォーマンスを示す。これらの指標を@Seconds秒間隔で2回取得し、差分を分析することで、その期間中のパフォーマンス問題を特定できる。

**通知の送信タイミング**：sp_BlitzFirstの行1396で、DMVからデータを取得する直前にRAISERRORが発行される。これは調査クエリの実行前の重要なデータ収集フェーズである。

**通知の受信者**：SSMSやその他のSQLクライアントツールを使用してストアドプロシージャを実行しているDBAまたはシステム管理者。

**通知内容の概要**：「Capturing first pass of wait stats, perfmon counters, file stats」というメッセージが出力され、3種類のパフォーマンスデータのキャプチャ開始を示す。

**期待されるアクション**：DBAはこのメッセージを確認することで、パフォーマンスデータの初回収集が開始されたことを把握できる。この後、調査クエリが実行され、@Seconds秒待機後に第2パスのキャプチャが行われる。

## 通知種別

コンソール出力（RAISERROR WITH NOWAIT）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（WITH NOWAITによる即時出力） |
| 優先度 | 低（情報レベル - Severity 10） |
| リトライ | なし |

### 送信先決定ロジック

SSMSのメッセージペインまたはSQLクライアントツールの標準出力に対して自動的に送信される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| メッセージレベル | 10（情報） |
| ステート | 1 |
| 形式 | テキスト |

### 本文テンプレート

```
Capturing first pass of wait stats, perfmon counters, file stats
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ストアドプロシージャ実行 | sp_BlitzFirst実行 | 常に送信 | パフォーマンスデータ収集時に必ず出力 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | このメッセージは常に出力される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[sp_BlitzFirst開始] --> B[バージョン判定・初期設定]
    B --> C[プランキャッシュキャプチャ（オプション）]
    C --> D[RAISERROR 'Capturing first pass...']
    D --> E[#WaitStatsにINSERT]
    E --> F[#FileStatsにINSERT]
    F --> G[#PerfmonStatsにINSERT]
    G --> H[調査クエリ実行へ]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| sys.dm_os_wait_stats | 累積待機統計の取得 | オンプレミスSQL Server用 |
| sys.dm_db_wait_stats | 累積待機統計の取得 | Azure SQL Database用 |
| sys.dm_os_waiting_tasks | 現在待機中のタスク情報 | アクティブな待機の取得 |
| sys.dm_os_performance_counters | パフォーマンスカウンタ値 | Perfmon相当のデータ |
| sys.dm_io_virtual_file_stats | ファイルI/O統計 | データ/ログファイルの統計 |

### テーブル別参照項目詳細

#### sys.dm_os_wait_stats / sys.dm_db_wait_stats

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| wait_type | 待機種別 | ##WaitCategoriesで除外されていない待機 |
| wait_time_ms | 待機時間（ミリ秒） | 全件 |
| signal_wait_time_ms | シグナル待機時間 | 全件 |
| waiting_tasks_count | 待機タスク数 | 全件 |

#### sys.dm_os_performance_counters

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| object_name | オブジェクト名 | #PerfmonCountersで定義されたカウンタ |
| counter_name | カウンタ名 | 同上 |
| instance_name | インスタンス名 | 同上 |
| cntr_value | カウンタ値 | 同上 |
| cntr_type | カウンタタイプ | 同上 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| #WaitStats | INSERT | 待機統計のスナップショット |
| #FileStats | INSERT | ファイルI/O統計のスナップショット |
| #PerfmonStats | INSERT | パフォーマンスカウンタのスナップショット |

#### #WaitStats

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | Pass | 1 | 第1パスを示す |
| INSERT | SampleTime | SYSDATETIMEOFFSET() | サンプリング時刻 |
| INSERT | wait_type | DMVから取得 | 待機種別 |
| INSERT | wait_time_ms | DMVから取得 | 累積待機時間 |
| INSERT | thread_time_ms | @thread_time_ms | スレッド時間 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | RAISERRORは情報レベルのため、エラーは発生しない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- VIEW SERVER STATE権限が必要
- 収集されるデータはシステムレベルの統計情報であり、機密データは含まれない

## 備考

- @Seconds = 0の場合、サーバー起動以降の累積データのみが取得され、比較は行われない
- Azure SQL Databaseではsys.dm_db_wait_statsが使用される

---

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

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

### 推奨読解順序

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

パフォーマンスデータを格納する一時テーブルの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | #WaitStats, #FileStats, #PerfmonStatsテーブルの定義 |
| 1-2 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ##WaitCategoriesグローバル一時テーブル（除外待機定義） |

**読解のコツ**: Pass列で第1パス（1）と第2パス（2）を区別する。

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

通知が発行される箇所を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行1396のRAISERROR文 |

**主要処理フロー**:
1. **行1396**: RAISERROR - 第1パスキャプチャ開始通知
2. **行1397-1475**: #WaitStatsへのINSERT（動的SQL）
3. **行1477-1507**: #PerfmonStatsへのINSERT
4. **行1501-1507**: #FileStatsへのINSERT（別途）

#### Step 3: 待機統計収集ロジックを理解する

待機統計の収集と除外ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行1397-1475の動的SQL構築 |

**主要処理フロー**:
- **行1412-1422**: sys.dm_os_waiting_tasksからアクティブ待機を取得
- **行1424-1429**: sys.dm_os_wait_stats（またはdm_db_wait_stats）から累積待機を取得
- **行1457-1464**: ##WaitCategoriesによる除外フィルタリング

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

```
sp_BlitzFirst
    |
    +-- RAISERROR 'Capturing first pass of wait stats...'
    |
    +-- 待機統計収集
    |       |
    |       +-- sys.dm_os_waiting_tasks（アクティブ待機）
    |       +-- sys.dm_os_wait_stats / dm_db_wait_stats（累積待機）
    |       +-- ##WaitCategories（除外フィルタ）
    |       +-- #WaitStats（結果格納）
    |
    +-- ファイル統計収集
    |       |
    |       +-- sys.dm_io_virtual_file_stats
    |       +-- #FileStats（結果格納）
    |
    +-- パフォーマンスカウンタ収集
            |
            +-- sys.dm_os_performance_counters
            +-- #PerfmonCounters（フィルタ）
            +-- #PerfmonStats（結果格納）
```

### データフロー図

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

sys.dm_os_wait_stats ---------> RAISERROR ---------------> クライアントへの
sys.dm_os_waiting_tasks            |                       メッセージ表示
                                   v
                              #WaitStats
                              (Pass=1)

sys.dm_io_virtual_file_stats --> #FileStats
                              (Pass=1)

sys.dm_os_performance_counters --> #PerfmonStats
                                (Pass=1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | メインストアドプロシージャ（行1394-1507） |
