# 画面設計書 4-sp_BlitzFirst 診断結果画面

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzFirstストアドプロシージャが出力する、リアルタイムパフォーマンス診断結果画面の設計仕様を記載する。

### 本画面の処理概要

sp_BlitzFirst診断結果画面は、SQL Serverの「今この瞬間」のパフォーマンス問題を診断し、優先度付きのリストで表示する画面である。現在進行中の問題を即座に把握し、緊急対応が必要な項目を特定するために使用する。

**業務上の目的・背景**：本番環境でパフォーマンス問題が発生した際、「今何が起きているか」を即座に把握することが重要である。sp_BlitzFirstは、指定した秒数（デフォルト5秒）のサンプリング期間で、Wait Stats、File Stats、Perfmon Countersの変化を計測し、その間に検出された問題を優先度順に表示する。sp_Blitzが「サーバー全体の健康状態」を診断するのに対し、sp_BlitzFirstは「現在のパフォーマンス状態」に焦点を当てる。これにより、DBAは問題の即時診断と緊急対応を効率的に行える。

**画面へのアクセス方法**：SQL Server Management Studio (SSMS)またはAzure Data Studioなどのクエリツールから、`EXEC sp_BlitzFirst`を実行することで結果画面にアクセスする。@Secondsパラメータでサンプリング間隔を、@ExpertModeで詳細度を制御できる。

**主要な操作・処理内容**：
1. サンプリング開始時点のWait Stats、File Stats、Perfmon Countersを取得
2. 指定秒数（@Seconds、デフォルト5秒）待機
3. サンプリング終了時点の統計を取得し、差分を計算
4. 検出された問題を優先度順にリスト表示
5. @ExpertMode=1の場合、sp_BlitzWhoを開始時・終了時に呼び出し、詳細統計も表示

**画面遷移**：
- この画面から遷移できる画面：sp_BlitzCache結果画面（クエリ問題検出時）、sp_BlitzLock結果画面（ブロッキング検出時）、sp_BlitzFirst詳細統計画面（@ExpertMode=1時）
- この画面に遷移してくる画面：エントリーポイント（パフォーマンス問題発生時）

**権限による表示制御**：VIEW SERVER STATE権限が必要。sp_BlitzWhoの呼び出しには追加の権限は不要だが、sp_BlitzWhoがインストールされている必要がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | sp_BlitzFirst | 主機能 | リアルタイムでパフォーマンス問題を診断し、優先度付きで結果を表示 |
| 6 | sp_BlitzWho | 補助機能 | サンプリング開始時と終了時にsp_BlitzWhoを呼び出し、実行中クエリを取得 |

## 画面種別

一覧（リアルタイム診断結果表示）

## URL/ルーティング

```sql
-- 基本実行（5秒サンプリング）
EXEC sp_BlitzFirst;

-- サンプリング間隔を変更
EXEC sp_BlitzFirst @Seconds = 30;

-- 詳細モード（ExpertMode）
EXEC sp_BlitzFirst @ExpertMode = 1;

-- 起動以降の統計
EXEC sp_BlitzFirst @SinceStartup = 1;

-- 過去データの参照
EXEC sp_BlitzFirst
    @AsOf = '2024-01-15 10:00:00',
    @OutputDatabaseName = 'DBAtools',
    @OutputSchemaName = 'dbo',
    @OutputTableName = 'BlitzFirst';
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|---------|-------------|------|
| @Help | TINYINT | 0 | 1を指定するとヘルプメッセージを表示 |
| @AsOf | DATETIMEOFFSET | NULL | 過去データ参照時の日時指定 |
| @ExpertMode | TINYINT | 0 | 詳細モード（0:標準/1:詳細+sp_BlitzWho/2:詳細のみ） |
| @Seconds | INT | 5 | サンプリング間隔（秒） |
| @OutputType | VARCHAR(20) | 'TABLE' | 出力形式 |
| @OutputServerName | NVARCHAR(256) | NULL | 出力先サーバー名 |
| @OutputDatabaseName | NVARCHAR(256) | NULL | 出力先データベース名 |
| @OutputSchemaName | NVARCHAR(256) | NULL | 出力先スキーマ名 |
| @OutputTableName | NVARCHAR(256) | NULL | 出力先テーブル名 |
| @OutputTableNameFileStats | NVARCHAR(256) | NULL | ファイル統計出力テーブル |
| @OutputTableNamePerfmonStats | NVARCHAR(256) | NULL | Perfmon統計出力テーブル |
| @OutputTableNameWaitStats | NVARCHAR(256) | NULL | Wait統計出力テーブル |
| @OutputTableNameBlitzCache | NVARCHAR(256) | NULL | BlitzCache出力テーブル |
| @OutputTableNameBlitzWho | NVARCHAR(256) | NULL | BlitzWho出力テーブル |
| @OutputTableRetentionDays | TINYINT | 7 | 出力テーブルの保持日数 |
| @FileLatencyThresholdMS | INT | 100 | ファイルレイテンシ閾値（ms） |
| @SinceStartup | TINYINT | 0 | 1=サーバー起動以降の統計を表示 |
| @ShowSleepingSPIDs | TINYINT | 0 | 1=スリープ中のSPIDも表示 |
| @BlitzCacheSkipAnalysis | BIT | 1 | BlitzCache呼び出し時の分析スキップ |
| @MemoryGrantThresholdPct | DECIMAL(5,2) | 15.00 | メモリグラント警告閾値（%） |
| @LogMessage | NVARCHAR(4000) | NULL | カスタムログメッセージ |
| @Debug | BIT | 0 | デバッグモード |

## 表示項目

### メイン結果セット（Findings）

| 列名 | データ型 | 説明 |
|-----|---------|------|
| Priority | TINYINT | 優先度（1が最も緊急） |
| FindingsGroup | VARCHAR(50) | 問題のカテゴリ |
| Finding | VARCHAR(200) | 問題の名称 |
| URL | VARCHAR(200) | 詳細情報へのリンク |
| Details | NVARCHAR(4000) | 問題の詳細説明 |
| HowToStopIt | NVARCHAR(MAX) | 問題の解決方法 |
| QueryPlan | XML | 関連するクエリプラン |
| QueryText | NVARCHAR(MAX) | 関連するクエリテキスト |

### 主要な検出項目

| Finding | 説明 | 優先度目安 |
|---------|------|-----------|
| Data File Growing | データファイルが拡張中 | 高 |
| Log File Growing | ログファイルが拡張中 | 高 |
| Backup Running | バックアップ実行中 | 中 |
| Restore Running | リストア実行中 | 中 |
| DBCC Running | DBCCコマンド実行中 | 中 |
| High CPU | CPU使用率が高い | 高 |
| High Wait Stats | 特定の待機が多い | 中〜高 |
| Memory Pressure | メモリ圧迫 | 高 |
| Poison Wait | 問題のある待機タイプ | 高 |
| File Latency | ファイルI/Oレイテンシが高い | 中〜高 |

## イベント仕様

### 1-プロシージャ実行（標準モード）

ユーザーがsp_BlitzFirstを実行すると、以下の処理フローが実行される：

1. パラメータの検証とデフォルト値の設定
2. 一時テーブルの作成（#BlitzFirstResults、#WaitStats、#FileStats、#PerfmonStats等）
3. サンプリング開始時点の統計取得
4. @Seconds秒間待機（WAITFOR DELAY）
5. サンプリング終了時点の統計取得
6. 差分計算と問題検出
7. 結果の返却

### 2-ExpertMode別の動作

| @ExpertMode | 動作 |
|------------|------|
| 0 | 標準診断結果のみ |
| 1 | sp_BlitzWho（開始時・終了時）+ Wait Stats + Perfmon + File Stats |
| 2 | Wait Stats + Perfmon + File Stats（sp_BlitzWhoなし） |

### 3-@SinceStartup=1の動作

| 動作 | 説明 |
|-----|------|
| @Seconds自動設定 | 0に設定される |
| @ExpertMode自動設定 | 0の場合1に変更 |
| 統計範囲 | サーバー起動時点からの累計統計 |

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プロシージャ実行 | #BlitzFirstResults | INSERT | 診断結果を一時テーブルに格納 |
| プロシージャ実行 | #WaitStats | INSERT | Wait統計を格納 |
| プロシージャ実行 | #FileStats | INSERT | ファイル統計を格納 |
| プロシージャ実行 | #PerfmonStats | INSERT | Perfmon統計を格納 |
| 出力テーブル指定時 | @OutputTableName | INSERT | 結果を永続テーブルに保存 |

### テーブル別更新項目詳細

#### #BlitzFirstResults（一時テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | CheckID | チェック項目固有のID | 各検出項目に対応 |
| INSERT | Priority | 問題の優先度 | 値が小さいほど重要 |
| INSERT | FindingsGroup | 問題カテゴリ | 動的に設定 |
| INSERT | Finding | 問題名 | 検出内容に応じて設定 |
| INSERT | URL | 参照URL | FirstResponderKit.org等 |
| INSERT | Details | 詳細情報 | 動的に生成 |
| INSERT | HowToStopIt | 解決方法 | 問題に応じて設定 |
| INSERT | QueryPlan | 実行プラン | NULL許容 |
| INSERT | QueryText | クエリテキスト | NULL許容 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | 情報 | Setting up configuration variables | 処理開始時（RAISERROR） |
| - | 情報 | Now starting diagnostic analysis | 診断開始時 |
| - | エラー | This procedure should be called with a value for all @Output* parameters | @OutputType='NONE'で出力パラメータ不足時 |
| - | 情報 | sp_BlitzWho is not installed in the current database_files | sp_BlitzWhoが未インストール時 |
| - | 情報 | LogMessage saved to table | @LogMessage指定時 |

## 例外処理

| 例外状況 | 動作 |
|---------|------|
| sp_BlitzWhoが未インストール | 警告メッセージを表示し、sp_BlitzWho呼び出しをスキップ |
| @OutputType='NONE'で出力パラメータ不足 | エラーメッセージを表示して終了 |
| 出力データベースが存在しない | エラーメッセージを表示して終了 |
| Azure SQL Database | dm_cloud_database_epochから起動時刻を取得 |

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 既知の制限事項：
  - @OutputServerNameは現時点で未実装
  - 括弧付きの@OutputDatabaseName等は正常動作しない可能性あり
  - #CustomPerfmonCountersが他セッションに存在する場合エラーになる可能性

---

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

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

### 推奨読解順序

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

まず、結果格納用の一時テーブル構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行393-421: #BlitzFirstResultsテーブル定義 |
| 1-2 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行423-433: #WaitStatsテーブル定義 |
| 1-3 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行435-456: #FileStatsテーブル定義 |
| 1-4 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行484-495: #PerfmonStatsテーブル定義 |

**読解のコツ**: 各一時テーブルにPassカラムがあり、サンプリング開始時（Pass 1）と終了時（Pass 2）を区別している。

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

プロシージャのシグネチャとパラメータ処理を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行6-43: ALTER PROCEDUREとパラメータ定義 |
| 2-2 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行50-55: バージョン情報とVersionCheckMode処理 |
| 2-3 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | 行57-112: @Help処理 |

**主要処理フロー**:
1. **行50**: バージョン設定 `@Version = '8.29', @VersionDate = '20260203'`
2. **行11**: @Secondsデフォルト値 5秒
3. **行10**: @ExpertModeデフォルト値 0

#### Step 3: サンプリング処理を理解する

Wait Stats、File Stats、Perfmon Countersのサンプリングロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | サンプリング開始/終了処理部分 |
| 3-2 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | sp_BlitzWho呼び出し部分（行283-293） |

**主要処理フロー**:
- **行137**: @BlitzWhoコマンド構築
- **行283-293**: @ExpertMode=1かつ@Seconds>0の場合、sp_BlitzWhoを呼び出し

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

```
sp_BlitzFirst
    │
    ├─ パラメータ検証・初期化
    │      ├─ バージョンチェック
    │      ├─ @Help処理
    │      └─ @OutputType処理
    │
    ├─ sp_BlitzWho呼び出し（開始時、@ExpertMode=1）
    │
    ├─ サンプリング開始（Pass 1）
    │      ├─ #WaitStatsへINSERT
    │      ├─ #FileStatsへINSERT
    │      └─ #PerfmonStatsへINSERT
    │
    ├─ WAITFOR DELAY (@Seconds秒)
    │
    ├─ サンプリング終了（Pass 2）
    │      ├─ #WaitStatsへINSERT
    │      ├─ #FileStatsへINSERT
    │      └─ #PerfmonStatsへINSERT
    │
    ├─ 差分計算・問題検出
    │      └─ #BlitzFirstResultsへINSERT
    │
    ├─ sp_BlitzWho呼び出し（終了時、@ExpertMode=1）
    │
    └─ 結果出力
           ├─ Findings結果セット
           └─ 統計結果セット（@ExpertMode時）
```

### データフロー図

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

@パラメータ群 ───────▶ sp_BlitzFirst ─────────────────▶ Findings
                           │                             結果セット
                           ▼
    sys.dm_os_wait_stats ──▶ #WaitStats ──────────▶ Wait Stats
    sys.dm_io_virtual_file_stats ──▶ #FileStats ─▶ File Stats
    sys.dm_os_performance_counters ──▶ #PerfmonStats ─▶ Perfmon
                           │
                           ▼
                    sp_BlitzWho ──────────────────▶ 実行中クエリ
                    （@ExpertMode=1時）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | メインプロシージャ定義 |
| sp_BlitzWho.sql | `sp_BlitzWho.sql` | ソース | 実行中クエリ取得（@ExpertMode時に呼び出し） |
