# 機能設計書 3-sp_BlitzFirst

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzFirstストアドプロシージャの機能設計について記載する。sp_BlitzFirstは現在のパフォーマンス問題をリアルタイムで診断し、優先度付きのアドバイスを出力する診断ツールである。

### 本機能の処理概要

sp_BlitzFirstは、SQL Serverの現在のパフォーマンス状態を即座に診断し、「今何が起きているか」を特定するためのストアドプロシージャである。デフォルトで5秒間のサンプリングを実行し、その間の変化を分析する。

**業務上の目的・背景**：本番環境でパフォーマンス問題が発生した際、DBAは「今この瞬間」に何が起きているかを素早く把握する必要がある。sp_BlitzFirstは、待機統計、ファイルI/O、Perfmonカウンター、実行中クエリなどを一度に収集・分析し、問題の原因を迅速に特定することを支援する。

**機能の利用シーン**：
- パフォーマンス問題発生時の緊急診断
- 定期的なパフォーマンス監視（テーブル出力でログ記録）
- ベースライン取得（@SinceStartup=1）
- リアルタイムクエリ監視

**主要な処理内容**：
1. サンプリング開始時点のスナップショット取得
2. 指定秒数（デフォルト5秒）の待機
3. サンプリング終了時点のスナップショット取得
4. 差分計算と問題検出
5. 優先度付き結果の出力

**関連システム・外部連携**：
- sp_BlitzWho: 実行中クエリの取得
- sp_BlitzCache: キャッシュ分析（オプション）
- 各種DMV（待機統計、ファイル統計、Perfmonカウンター）

**権限による制御**：
- VIEW SERVER STATE権限が必要
- テーブル出力時は対象テーブルへのINSERT権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | sp_BlitzFirst 診断結果画面 | 主機能 | リアルタイムでパフォーマンス問題を診断し、優先度付きで結果を表示 |
| 5 | sp_BlitzFirst 詳細統計画面（ExpertMode） | 主機能 | @ExpertMode=1時にWait Stats、Perfmon Counters、File Stats等の詳細情報を表示 |

## 機能種別

リアルタイム診断 / データ分析 / モニタリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| @LogMessage | NVARCHAR(4000) | No | ログメッセージ記録用 | NULL許可 |
| @Help | TINYINT | No | ヘルプ表示 | デフォルト0 |
| @AsOf | DATETIMEOFFSET | No | 過去データ参照日時 | NULL許可 |
| @ExpertMode | TINYINT | No | 詳細モード（0/1） | デフォルト0 |
| @Seconds | INT | No | サンプリング秒数 | デフォルト5 |
| @OutputType | VARCHAR(20) | No | 出力形式 | デフォルトTABLE |
| @OutputServerName | NVARCHAR(256) | No | 出力先サーバー | NULL許可 |
| @OutputDatabaseName | NVARCHAR(256) | No | 出力先データベース | NULL許可 |
| @OutputSchemaName | NVARCHAR(256) | No | 出力先スキーマ | NULL許可 |
| @OutputTableName | NVARCHAR(256) | No | 出力先テーブル | NULL許可 |
| @OutputTableNameFileStats | NVARCHAR(256) | No | ファイル統計出力テーブル | NULL許可 |
| @OutputTableNamePerfmonStats | NVARCHAR(256) | No | Perfmon統計出力テーブル | NULL許可 |
| @OutputTableNameWaitStats | NVARCHAR(256) | No | 待機統計出力テーブル | NULL許可 |
| @OutputTableNameBlitzCache | NVARCHAR(256) | No | BlitzCache出力テーブル | NULL許可 |
| @OutputTableNameBlitzWho | NVARCHAR(256) | No | BlitzWho出力テーブル | NULL許可 |
| @OutputResultSets | NVARCHAR(500) | No | 出力結果セット指定 | デフォルト値あり |
| @OutputTableRetentionDays | TINYINT | No | テーブル保持日数 | デフォルト7 |
| @FileLatencyThresholdMS | INT | No | ファイルレイテンシ閾値(ms) | デフォルト100 |
| @SinceStartup | TINYINT | No | 起動時からの統計を使用 | デフォルト0 |
| @ShowSleepingSPIDs | TINYINT | No | スリープSPIDを表示 | デフォルト0 |
| @BlitzCacheSkipAnalysis | BIT | No | BlitzCache分析スキップ | デフォルト1 |
| @MemoryGrantThresholdPct | DECIMAL(5,2) | No | メモリ付与閾値(%) | デフォルト15.00 |
| @Debug | BIT | No | デバッグモード | デフォルト0 |
| @Version | VARCHAR(30) | No | バージョン（OUTPUT） | 出力専用 |
| @VersionDate | DATETIME | No | バージョン日付（OUTPUT） | 出力専用 |

### 入力データソース

- sys.dm_os_wait_stats: 待機統計
- sys.dm_io_virtual_file_stats: ファイルI/O統計
- sys.dm_os_performance_counters: Perfmonカウンター
- sys.dm_exec_requests: 実行中リクエスト
- sys.databases: データベース情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Priority | TINYINT | 問題の優先度 |
| FindingsGroup | VARCHAR(50) | 問題カテゴリ |
| Finding | VARCHAR(200) | 問題の名称 |
| URL | VARCHAR(200) | 詳細情報リンク |
| Details | NVARCHAR(4000) | 問題の詳細 |
| HowToStopIt | NVARCHAR(MAX) | 対処方法 |
| QueryPlan | XML | 関連クエリプラン |
| QueryText | NVARCHAR(MAX) | 関連クエリテキスト |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証と初期化
   └─ 出力先、サンプリング秒数の設定

2. 開始時スナップショット（Pass 1）
   └─ 待機統計、ファイル統計、Perfmonカウンター取得

3. sp_BlitzWho実行（ExpertMode時）
   └─ 現在実行中のクエリ情報取得

4. サンプリング待機
   └─ WAITFOR DELAY（@Seconds秒）

5. 終了時スナップショット（Pass 2）
   └─ 再度各種統計取得

6. 差分計算と問題検出
   └─ Pass 1とPass 2の差分から問題を特定

7. sp_BlitzWho実行（ExpertMode時）
   └─ 終了時点の実行中クエリ取得

8. 結果出力
   └─ 優先度順に結果セット返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ出力]
    C --> Z[終了]
    B -->|No| D{@LogMessage指定?}
    D -->|Yes| E[メッセージをテーブルに記録]
    E --> Z
    D -->|No| F[パラメータ初期化]
    F --> G[Pass 1: 開始時スナップショット]
    G --> H{@ExpertMode=1?}
    H -->|Yes| I[sp_BlitzWho実行]
    H -->|No| J[WAITFOR DELAY]
    I --> J
    J --> K[Pass 2: 終了時スナップショット]
    K --> L[差分計算・問題検出]
    L --> M{@ExpertMode=1?}
    M -->|Yes| N[sp_BlitzWho実行]
    M -->|No| O[結果出力]
    N --> O
    O --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトサンプリング | 5秒間のサンプリングを実行 | @Seconds未指定時 |
| BR-002 | SinceStartup | @SinceStartup=1時は@Seconds=0 | ベースライン取得 |
| BR-003 | ExpertMode自動有効化 | @SinceStartup=1時は@ExpertMode=1に | ベースライン取得 |
| BR-004 | ファイルレイテンシ閾値 | 100ms以上を問題として検出 | @FileLatencyThresholdMS |
| BR-005 | 保持期間 | 7日以上古いデータを自動削除 | @OutputTableRetentionDays |

### 計算ロジック

**待機統計差分計算**:
```sql
wait_time_ms_delta = Pass2.wait_time_ms - Pass1.wait_time_ms
```

**ファイルレイテンシ計算**:
```sql
avg_stall_read_ms = io_stall_read_ms / num_of_reads
avg_stall_write_ms = io_stall_write_ms / num_of_writes
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 参照 | sys.dm_os_wait_stats | SELECT | 待機統計取得 |
| 参照 | sys.dm_io_virtual_file_stats | SELECT | ファイルI/O統計 |
| 参照 | sys.dm_os_performance_counters | SELECT | Perfmonカウンター |
| 挿入 | BlitzFirst | INSERT | 結果出力（オプション） |
| 挿入 | BlitzFirst_WaitStats | INSERT | 待機統計出力（オプション） |
| 挿入 | BlitzFirst_FileStats | INSERT | ファイル統計出力（オプション） |
| 挿入 | BlitzFirst_PerfmonStats | INSERT | Perfmon出力（オプション） |
| 削除 | 各出力テーブル | DELETE | 古いデータの削除 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | CheckID, Priority, FindingsGroup, Finding等 | 検出された問題 | 処理中に挿入 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 出力パラメータエラー | @OutputType='NONE'で出力先未指定 | RAISERRORでエラー通知 |
| - | sp_BlitzWho未インストール | sp_BlitzWhoが見つからない | メッセージ出力、処理継続 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 通常実行: @Seconds + 数秒（デフォルト約7-8秒）
- @SinceStartup=1: サンプリングなしのため高速

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

- VIEW SERVER STATE権限が必要
- テーブル出力時は対象データベース・テーブルへの適切な権限が必要

## 備考

- バージョン: 8.29（2026年2月3日時点）
- sp_BlitzWhoとの連携でより詳細な診断が可能

---

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

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

### 推奨読解順序

#### 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一時テーブル定義 |

**読解のコツ**: 各一時テーブルがサンプリングデータの格納先。Pass列で開始時（1）と終了時（2）を区別している。

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

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

**主要処理フロー**:
1. **46-48行目**: SET NOCOUNT ON、STATISTICS XML OFF、READ UNCOMMITTED設定
2. **50行目**: バージョン情報設定（@Version = '8.29'）
3. **137行目**: sp_BlitzWho呼び出しコマンド準備

#### Step 3: sp_BlitzWho連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | **283-293行目**: sp_BlitzWho実行処理 |

**主要処理フロー**:
- **285-288行目**: sp_BlitzWhoの存在確認
- **291行目**: sp_BlitzWho実行

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

```
sp_BlitzFirst
    │
    ├─ sp_BlitzWho (開始時・終了時)
    │
    ├─ sp_BlitzCache (オプション)
    │
    ├─ sys.dm_os_wait_stats (待機統計)
    │
    ├─ sys.dm_io_virtual_file_stats (ファイルI/O)
    │
    ├─ sys.dm_os_performance_counters (Perfmon)
    │
    └─ sp_executesql (動的SQL)
```

### データフロー図

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

パラメータ ──────────────────▶ パラメータ検証 ─────────────────▶ #BlitzFirstResults
   │                              │                                   │
   │                         Pass 1                                   │
   │                              ▼                                   │
dm_os_wait_stats ────────────▶ 開始時スナップショット ───────────▶ #WaitStats
   │                              │                                   │
dm_io_virtual_file_stats ────▶ ファイル統計取得 ─────────────────▶ #FileStats
   │                              │                                   │
dm_os_performance_counters ──▶ Perfmon取得 ──────────────────────▶ #PerfmonStats
   │                              │                                   │
   │                         WAITFOR DELAY                            │
   │                              │                                   │
   │                         Pass 2                                   │
   │                              ▼                                   │
   └─────────────────────────▶ 終了時スナップショット ───────────▶ │
                                  │                                   │
                            差分計算・問題検出 ◀──────────────────────┘
                                  │
                                  ▼
                         [結果セット/テーブル]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | メインストアドプロシージャ定義 |
| sp_BlitzWho.sql | `sp_BlitzWho.sql` | 関連 | 実行中クエリ取得（呼び出し先） |
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | 関連 | キャッシュ分析（オプション呼び出し先） |
| sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 関連 | BlitzFirstテーブルからデータ取得 |
