# 帳票設計書 4-sp_BlitzFirst

## 概要

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

### 本帳票の処理概要

sp_BlitzFirstは、現在のパフォーマンス問題をリアルタイムで診断し、優先度付きリストを出力するストアドプロシージャである。Wait Stats、Perfmonカウンター、File Statsなどをサンプリングベースで分析し、「今まさに何が問題なのか」を特定する。指定した秒数間の差分を取得し、その期間中の問題を検出する。

**業務上の目的・背景**：SQL Serverでパフォーマンス問題が発生した際、「今何が起きているのか」を素早く把握することが重要である。本帳票は、DBAやオペレーターがリアルタイムで問題を診断し、迅速な対応を可能にすることを目的としている。また、定期的に実行してログを蓄積することで、履歴分析にも活用できる。

**帳票の利用シーン**：
- パフォーマンス問題発生時の緊急診断
- 定期的なパフォーマンス監視（ジョブ実行）
- システム負荷のベースライン収集
- 問題発生前後の比較分析
- 容量計画のためのデータ収集

**主要な出力内容**：
1. Priority（優先度）：問題の緊急度
2. FindingsGroup（検出グループ）：問題カテゴリ
3. Finding（検出内容）：具体的な問題
4. Wait Stats：待機統計の差分
5. Perfmon Stats：パフォーマンスカウンターの差分
6. File Stats：ファイルI/O統計の差分
7. BlitzCache結果：期間中のトップクエリ
8. BlitzWho結果：期間開始/終了時の実行中クエリ

**帳票の出力タイミング**：
- ストアドプロシージャ `EXEC sp_BlitzFirst` の手動実行時
- SQL Server Agentジョブによる定期実行時（推奨: 15分間隔）
- 監視ツールからの自動呼び出し時

**帳票の利用者**：
- データベース管理者（DBA）
- システムオペレーター
- パフォーマンスエンジニア
- オンコールエンジニア

## 帳票種別

リアルタイム診断レポート / パフォーマンス分析表

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力結果セット構成

| 結果セット | 説明 | 条件 |
|------------|------|------|
| BlitzWho_Start | サンプリング開始時の実行中クエリ | @ExpertMode=1 |
| Findings | 検出された問題一覧 | 常時 |
| FileStats | ファイルI/O統計 | @ExpertMode=1 |
| PerfmonStats | Perfmonカウンター | @ExpertMode=1 |
| WaitStats | 待機統計 | @ExpertMode=1 |
| BlitzCache | トップクエリ | @ExpertMode=1 |
| BlitzWho_End | サンプリング終了時の実行中クエリ | @ExpertMode=1 |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────────────────────────────────────┐
│  結果セット1: BlitzWho_Start（サンプリング開始時のクエリ）           │
├─────────────────────────────────────────────────────────────────────┤
│  session_id | elapsed_time | query_text | wait_info | ...           │
└─────────────────────────────────────────────────────────────────────┘
         ↓ @Seconds秒待機 ↓
┌─────────────────────────────────────────────────────────────────────┐
│  結果セット2: Findings（検出問題）                                   │
├─────────────────────────────────────────────────────────────────────┤
│  Priority | FindingsGroup | Finding | Details | HowToStopIt | ...   │
└─────────────────────────────────────────────────────────────────────┘
```

### 出力カラム詳細（Findings）

| No | 項目名 | 説明 | データ型 | 表示形式 |
|----|-------|------|----------|---------|
| 1 | Priority | 問題の優先度 | TINYINT | 数値 |
| 2 | FindingsGroup | 検出カテゴリ | VARCHAR(50) | テキスト |
| 3 | Finding | 検出内容 | VARCHAR(200) | テキスト |
| 4 | URL | 詳細情報URL | VARCHAR(200) | ハイパーリンク |
| 5 | Details | 詳細説明 | NVARCHAR(MAX) | テキスト |
| 6 | HowToStopIt | 対処方法 | NVARCHAR(MAX) | テキスト |
| 7 | QueryPlan | 実行プラン | XML | XML |
| 8 | QueryText | クエリテキスト | NVARCHAR(MAX) | テキスト |

### 出力カラム詳細（WaitStats）

| No | 項目名 | 説明 | データ型 |
|----|-------|------|----------|
| 1 | wait_type | 待機タイプ | NVARCHAR(60) |
| 2 | wait_time_ms | 待機時間（ミリ秒） | BIGINT |
| 3 | signal_wait_time_ms | シグナル待機時間 | BIGINT |
| 4 | waiting_tasks_count | 待機タスク数 | BIGINT |

## 出力条件

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @Help | TINYINT | 0 | 1でヘルプ表示 |
| @Seconds | INT | 5 | サンプリング間隔（秒） |
| @ExpertMode | TINYINT | 0 | 詳細モード |
| @OutputType | VARCHAR(20) | 'TABLE' | 出力形式 |
| @AsOf | DATETIMEOFFSET | NULL | 過去データ参照時の日時 |
| @OutputDatabaseName | NVARCHAR(256) | NULL | 出力先DB名 |
| @OutputSchemaName | NVARCHAR(256) | NULL | 出力先スキーマ名 |
| @OutputTableName | NVARCHAR(256) | NULL | BlitzFirst出力テーブル |
| @OutputTableNameFileStats | NVARCHAR(256) | NULL | FileStats出力テーブル |
| @OutputTableNamePerfmonStats | NVARCHAR(256) | NULL | Perfmon出力テーブル |
| @OutputTableNameWaitStats | NVARCHAR(256) | NULL | WaitStats出力テーブル |
| @OutputTableNameBlitzCache | NVARCHAR(256) | NULL | BlitzCache出力テーブル |
| @OutputTableNameBlitzWho | NVARCHAR(256) | NULL | BlitzWho出力テーブル |
| @OutputTableRetentionDays | TINYINT | 7 | データ保持日数 |
| @SinceStartup | TINYINT | 0 | 起動時からの累計 |
| @FileLatencyThresholdMS | INT | 100 | ファイル遅延閾値 |
| @CheckProcedureCache | TINYINT | 0 | プロシージャキャッシュチェック |
| @ShowSleepingSPIDs | TINYINT | 0 | スリープSPID表示 |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | Priority | 昇順 |
| 2 | FindingsGroup | 昇順 |
| 3 | Finding | 昇順 |

### 改ページ条件

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

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

### 参照DMV一覧

| DMV名 | 用途 | 結合条件 |
|-------|------|---------|
| sys.dm_os_wait_stats | 待機統計 | - |
| sys.dm_os_performance_counters | Perfmonカウンター | - |
| sys.dm_io_virtual_file_stats | ファイルI/O統計 | database_id, file_id |
| sys.dm_exec_requests | 実行中リクエスト | session_id |
| sys.dm_exec_sessions | セッション情報 | session_id |
| sys.dm_os_sys_info | システム情報 | - |
| sys.dm_exec_query_stats | クエリ統計（差分計算用） | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| wait_time_delta | 終了時wait_time_ms - 開始時wait_time_ms | - | 期間中の待機時間 |
| wait_time_per_minute | wait_time_delta / (Seconds / 60) | 小数点以下2桁 | 分あたりの待機 |
| io_stall_delta | 終了時io_stall - 開始時io_stall | - | 期間中のI/O遅延 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[sp_BlitzFirst実行] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ表示して終了]
    B -->|No| D{@LogMessage指定?}
    D -->|Yes| E[メッセージをログに記録]
    D -->|No| F{@AsOf指定?}
    F -->|Yes| G[過去データを取得]
    F -->|No| H[サンプリング開始]
    H --> I[開始時のBlitzWho実行]
    I --> J[開始時の統計を取得]
    J --> K[@Seconds秒待機]
    K --> L[終了時の統計を取得]
    L --> M[差分計算]
    M --> N[問題検出]
    N --> O[BlitzCache実行]
    O --> P[終了時のBlitzWho実行]
    P --> Q{出力先テーブル指定?}
    Q -->|Yes| R[各テーブルに書き込み]
    Q -->|No| S[結果セット返却]
    E --> T[終了]
    G --> T
    R --> T
    S --> T
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力パラメータ不足 | NONE時に@Output*未指定 | @Output* parameters required | 必須パラメータを指定 |
| データベース不存在 | 出力先DBが存在しない | 出力時エラー | 出力先DBを事前作成 |
| sp_BlitzWho未インストール | sp_BlitzWhoが存在しない | sp_BlitzWho is not installed | sp_BlitzWhoをインストール |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 検出問題数 + 各統計の行数 |
| 目標出力時間 | @Seconds + 10秒以内 |
| 同時出力数上限 | 制限なし |

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

- VIEW SERVER STATE権限が必要
- 出力テーブルには機密情報（クエリテキスト等）が含まれる可能性あり
- @OutputTableRetentionDaysで自動削除設定可能
- ログテーブルへのアクセス制御が必要

## 備考

- バージョン: 8.29（2026年2月3日リリース）
- ライセンス: MIT License
- 公式サイト: http://FirstResponderKit.org
- sp_BlitzWho、sp_BlitzCacheと連携動作

---

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

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

### 推奨読解順序

#### 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列（1=開始時、2=終了時）で差分計算のタイミングを識別している点に注意。

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

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

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

**主要処理フロー**:
1. **行50**: バージョン情報の設定
2. **行57-112**: @Help=1の場合のヘルプ出力
3. **行192-241**: @LogMessageの処理（ログ記録機能）
4. **行283-293**: サンプリング開始時のBlitzWho呼び出し

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

```
sp_BlitzFirst (エントリーポイント)
    │
    ├─ パラメータヘルプ表示 (@Help = 1)
    │
    ├─ ログメッセージ記録 (@LogMessage指定時)
    │      └─ 出力テーブルに直接INSERT
    │
    ├─ 過去データ参照 (@AsOf指定時)
    │      └─ 出力テーブルからSELECT
    │
    └─ リアルタイム診断（メイン処理）
           ├─ sp_BlitzWho呼び出し（開始時）
           │
           ├─ サンプリング開始
           │      ├─ #WaitStats (Pass=1)
           │      ├─ #FileStats (Pass=1)
           │      └─ #PerfmonStats (Pass=1)
           │
           ├─ WAITFOR DELAY @Seconds
           │
           ├─ サンプリング終了
           │      ├─ #WaitStats (Pass=2)
           │      ├─ #FileStats (Pass=2)
           │      └─ #PerfmonStats (Pass=2)
           │
           ├─ 差分計算と問題検出
           │
           ├─ sp_BlitzCache呼び出し
           │
           └─ sp_BlitzWho呼び出し（終了時）
```

### データフロー図

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

@Seconds指定 ──────────▶ sp_BlitzFirst ──────▶ #BlitzFirstResults
                               │                        │
dm_os_wait_stats ◀─────────────┤                        ├──▶ Findings
dm_os_performance_counters ◀───┤                        │
dm_io_virtual_file_stats ◀─────┤                        ├──▶ WaitStats
sp_BlitzWho ◀──────────────────┤                        │
sp_BlitzCache ◀────────────────┘                        ├──▶ FileStats
                                                        │
                                                        ├──▶ PerfmonStats
                                                        │
                                                        └──▶ 出力テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | メインストアドプロシージャ |
| sp_BlitzWho.sql | `sp_BlitzWho.sql` | ソース | 実行中クエリ取得 |
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | トップクエリ取得 |
| sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | ソース | 履歴データ分析 |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | スクリプト | 全スクリプトのインストール |
