# 帳票設計書 8-sp_BlitzAnalysis

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzAnalysisストアドプロシージャが出力するBlitzFirst履歴分析帳票の設計を記述する。

### 本帳票の処理概要

sp_BlitzAnalysisは、sp_BlitzFirstの出力テーブルから履歴データを集計・分析するストアドプロシージャである。BlitzFirst、FileStats、PerfmonStats、WaitStats、BlitzCache、BlitzWhoのログテーブルから指定期間のデータを取得し、パフォーマンストレンドや問題の発生頻度を分析する。

**業務上の目的・背景**：sp_BlitzFirstで収集した履歴データを活用し、時系列でのパフォーマンス分析を行うことは、問題の傾向把握や容量計画に不可欠である。本帳票は、DBAが蓄積されたパフォーマンスデータを効率的に分析し、過去の問題を調査したり、パフォーマンストレンドを把握することを目的としている。

**帳票の利用シーン**：
- 過去のパフォーマンス問題の調査
- 時間帯別のパフォーマンス傾向分析
- 問題発生頻度のレポート作成
- 容量計画のためのトレンド分析
- 定期的なパフォーマンスレビュー

**主要な出力内容**：
1. BlitzFirst Findings：期間中の検出問題とその頻度
2. Wait Stats：待機統計のトレンド
3. File Stats：ファイルI/O統計のトレンド
4. Perfmon Stats：Perfmonカウンターのトレンド
5. BlitzCache：期間中のトップクエリ
6. BlitzWho：期間中の実行クエリ履歴

**帳票の出力タイミング**：
- ストアドプロシージャ `EXEC sp_BlitzAnalysis` の手動実行時
- 定期的なパフォーマンスレビュー時
- 問題調査時

**帳票の利用者**：
- データベース管理者（DBA）
- パフォーマンスエンジニア
- システム管理者
- キャパシティプランナー

## 帳票種別

履歴分析レポート / トレンド分析帳票

## 利用画面

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

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 複数結果セット |
| 用紙サイズ | N/A（結果セットとして出力） |
| 向き | N/A |
| ファイル名 | N/A |
| 出力方法 | 結果セット返却 |
| 文字コード | NVARCHAR（Unicode） |

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

| 結果セット | 説明 | 条件 |
|------------|------|------|
| 1 | レポートウィンドウ情報 | 常時 |
| 2 | BlitzFirst Findingsサマリー | @OutputTableNameBlitzFirst指定時 |
| 3 | BlitzFirst Findings詳細 | @OutputTableNameBlitzFirst指定時 |
| 4 | Wait Statsトレンド | @OutputTableNameWaitStats指定時 |
| 5 | File Statsトレンド | @OutputTableNameFileStats指定時 |
| 6 | Perfmon Statsトレンド | @OutputTableNamePerfmonStats指定時 |
| 7 | BlitzCacheクエリ | @OutputTableNameBlitzCache指定時 |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット1: レポートウィンドウ                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  ServerToReportOn | PrioritiesToInclude | StartDatetime | EndDatetime       │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット2: BlitzFirst Findingsサマリー                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  Priority | FindingsGroup | Finding | TotalOccurrences | First/LastOccurrence│
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット4: Wait Statsトレンド                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  ServerName | CheckDate | wait_type | WaitsRank | wait_time_ms_delta | ...  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 出力カラム詳細（BlitzFirst Findingsサマリー）

| No | 項目名 | 説明 | データ型 | 表示形式 |
|----|-------|------|----------|---------|
| 1 | Priority | 優先度 | TINYINT | 数値 |
| 2 | FindingsGroup | 検出グループ | VARCHAR(50) | テキスト |
| 3 | Finding | 検出内容 | VARCHAR(200) | テキスト |
| 4 | TotalOccurrences | 発生回数 | INT | 数値 |
| 5 | FirstOccurrence | 初回発生日時 | DATETIMEOFFSET(7) | 日時 |
| 6 | LastOccurrence | 最終発生日時 | DATETIMEOFFSET(7) | 日時 |

### 出力カラム詳細（Wait Statsトレンド）

| No | 項目名 | 説明 | データ型 |
|----|-------|------|----------|
| 1 | ServerName | サーバー名 | NVARCHAR(128) |
| 2 | CheckDate | 取得日時 | DATETIMEOFFSET |
| 3 | wait_type | 待機タイプ | NVARCHAR(60) |
| 4 | WaitsRank | 待機ランク | INT |
| 5 | WaitCategory | 待機カテゴリ | NVARCHAR(60) |
| 6 | wait_time_ms_delta | 待機時間差分 | BIGINT |
| 7 | wait_time_minutes_delta | 待機時間（分）差分 | DECIMAL |
| 8 | wait_time_ms_per_wait | 待機あたりの時間 | DECIMAL |

## 出力条件

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @Help | TINYINT | 0 | 1でヘルプ表示 |
| @StartDate | DATETIMEOFFSET(7) | NULL | 分析開始日時（デフォルト: 1時間前） |
| @EndDate | DATETIMEOFFSET(7) | NULL | 分析終了日時（デフォルト: 現在） |
| @OutputDatabaseName | NVARCHAR(256) | 'DBAtools' | ログテーブルのDB名 |
| @OutputSchemaName | NVARCHAR(256) | 'dbo' | ログテーブルのスキーマ名 |
| @OutputTableNameBlitzFirst | NVARCHAR(256) | 'BlitzFirst' | BlitzFirstテーブル名 |
| @OutputTableNameFileStats | NVARCHAR(256) | 'BlitzFirst_FileStats' | FileStatsテーブル名 |
| @OutputTableNamePerfmonStats | NVARCHAR(256) | 'BlitzFirst_PerfmonStats' | PerfmonStatsテーブル名 |
| @OutputTableNameWaitStats | NVARCHAR(256) | 'BlitzFirst_WaitStats' | WaitStatsテーブル名 |
| @OutputTableNameBlitzCache | NVARCHAR(256) | 'BlitzCache' | BlitzCacheテーブル名 |
| @OutputTableNameBlitzWho | NVARCHAR(256) | 'BlitzWho' | BlitzWhoテーブル名 |
| @Servername | NVARCHAR(128) | @@SERVERNAME | 対象サーバー名 |
| @Databasename | NVARCHAR(128) | NULL | 対象データベース（フィルタ用） |
| @BlitzCacheSortorder | NVARCHAR(20) | 'cpu' | BlitzCacheソート順 |
| @MaxBlitzFirstPriority | INT | 249 | BlitzFirst最大優先度 |
| @ReadLatencyThreshold | INT | 100 | 読み取り遅延閾値（ms） |
| @WriteLatencyThreshold | INT | 100 | 書き込み遅延閾値（ms） |
| @WaitStatsTop | TINYINT | 10 | Wait Statsのトップ件数 |
| @Maxdop | INT | 1 | 並列度 |
| @BringThePain | BIT | 0 | 大量データ分析許可 |
| @Debug | BIT | 0 | デバッグモード |

### ソート順

| 結果セット | ソート項目 | 昇順/降順 |
|-----------|----------|---------|
| BlitzFirst | Priority, TotalOccurrences | 昇順, 降順 |
| Wait Stats | CheckDate, wait_time_ms_delta | 昇順, 降順 |
| File Stats | CheckDate | 昇順 |
| Perfmon Stats | CheckDate, counter_name | 昇順 |

### 改ページ条件

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

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| BlitzFirst | 検出問題履歴 | ServerName, CheckDate |
| BlitzFirst_FileStats_Deltas | ファイルI/O履歴 | ServerName, CheckDate |
| BlitzFirst_PerfmonStats_Actuals | Perfmon履歴 | ServerName, CheckDate |
| BlitzFirst_WaitStats_Deltas | 待機統計履歴 | ServerName, CheckDate |
| BlitzCache | クエリキャッシュ履歴 | ServerName, CheckDate |
| BlitzWho_Deltas | 実行クエリ履歴 | ServerName, CheckDate |

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

#### BlitzFirst

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| Priority | Priority | 1-@MaxBlitzFirstPriority | 優先度フィルタ |
| FindingsGroup | FindingsGroup | - | グループ化 |
| Finding | Finding | - | 検出内容 |
| CheckDate | FirstOccurrence/LastOccurrence | @StartDate-@EndDate | MIN/MAX |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| TotalOccurrences | COUNT(*) | - | 発生回数 |
| WaitsRank | ROW_NUMBER() OVER(PARTITION BY CheckDate ORDER BY wait_time_ms_delta DESC) | - | 待機ランク |
| wait_time_ms_per_wait | wait_time_ms_delta / waiting_tasks_count_delta | 小数点以下2桁 | 待機あたり時間 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[sp_BlitzAnalysis実行] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ表示して終了]
    B -->|No| D{@OutputDatabaseName存在確認}
    D -->|No| E[エラー: DB不存在]
    D -->|Yes| F[日付パラメータ設定]
    F --> G{@BlitzCacheSortorder検証}
    G -->|無効| H[エラー: 無効なソート順]
    G -->|有効| I[#BlitzFirstCounts作成]
    I --> J[レポートウィンドウ出力]
    J --> K{BlitzFirstテーブル存在?}
    K -->|Yes| L[BlitzFirst分析・出力]
    K -->|No| M[スキップメッセージ]
    L --> N{WaitStatsテーブル存在?}
    M --> N
    N -->|Yes| O[WaitStats分析・出力]
    N -->|No| P[スキップメッセージ]
    O --> Q{FileStatsテーブル存在?}
    P --> Q
    Q -->|Yes| R[FileStats分析・出力]
    Q -->|No| S[スキップメッセージ]
    R --> T[以降のテーブル処理...]
    S --> T
    T --> U[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| DB不存在 | @OutputDatabaseNameが存在しない | Invalid database name provided | 正しいDB名を指定 |
| 無効なソート順 | @BlitzCacheSortorderが無効 | Invalid sort option specified | 有効なソート順を指定 |
| テーブル不存在 | 指定テーブルが存在しない | No data available as the table cannot be found | テーブル名を確認 |
| 大量データ警告 | 4時間超のall分析 | @BringThePain = 1 が必要 | @BringThePainを設定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 分析期間とデータ収集頻度に依存 |
| 目標出力時間 | @Maxdop設定で調整 |
| 同時出力数上限 | 制限なし |

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

- 出力テーブルへの読み取りアクセスが必要
- クエリテキストには機密情報が含まれる可能性あり
- サーバー名、データベース名が出力される

## 備考

- バージョン: 8.29（2026年2月3日リリース）
- ライセンス: MIT License
- 公式サイト: http://FirstResponderKit.org
- sp_BlitzFirstでログを蓄積してから使用

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 行103-115: #BlitzFirstCounts一時テーブル定義 |

**読解のコツ**: 集計結果を格納するテーブル構造を確認すること。

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

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

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

**主要処理フロー**:
1. **行40**: バージョン情報の設定
2. **行47-73**: @Help=1の場合のヘルプ出力
3. **行88-101**: 出力テーブル名の完全修飾名構築

#### Step 3: 各テーブルの分析処理を理解する

BlitzFirst、WaitStats等の各テーブルに対する分析処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 行208-257: BlitzFirst分析SQL |
| 3-2 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 行294-365: WaitStats分析SQL |
| 3-3 | sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | 行367-442: FileStats分析SQL |

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

```
sp_BlitzAnalysis (エントリーポイント)
    │
    ├─ パラメータヘルプ表示 (@Help = 1)
    │
    ├─ パラメータ検証
    │      ├─ DB存在確認
    │      ├─ 日付デフォルト設定
    │      └─ ソート順検証
    │
    ├─ 一時テーブル作成
    │      └─ #BlitzFirstCounts
    │
    ├─ レポートウィンドウ出力
    │
    ├─ BlitzFirst分析
    │      ├─ Findingsサマリー
    │      └─ Findings詳細
    │
    ├─ WaitStats分析
    │      └─ トップ待機のトレンド
    │
    ├─ FileStats分析
    │      └─ I/O遅延のトレンド
    │
    ├─ PerfmonStats分析
    │      └─ カウンター値のトレンド
    │
    └─ BlitzCache分析
           └─ トップクエリ
```

### データフロー図

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

@StartDate/@EndDate ─────▶ sp_BlitzAnalysis ──────▶ レポートウィンドウ
                               │                        │
BlitzFirst ◀───────────────────┤                        ├──▶ Findingsサマリー
BlitzFirst_FileStats_Deltas ◀──┤                        │
BlitzFirst_PerfmonStats_Actuals◀┤                       ├──▶ Findings詳細
BlitzFirst_WaitStats_Deltas ◀──┤                        │
BlitzCache ◀───────────────────┤                        ├──▶ WaitStatsトレンド
BlitzWho_Deltas ◀──────────────┘                        │
                                                        ├──▶ FileStatsトレンド
                                                        │
                                                        └──▶ PerfmonStatsトレンド
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzAnalysis.sql | `sp_BlitzAnalysis.sql` | ソース | メインストアドプロシージャ |
| sp_BlitzFirst.sql | `sp_BlitzFirst.sql` | ソース | ログデータ収集元 |
| sp_BlitzCache.sql | `sp_BlitzCache.sql` | ソース | クエリキャッシュログ元 |
| sp_BlitzWho.sql | `sp_BlitzWho.sql` | ソース | 実行クエリログ元 |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | スクリプト | 全スクリプトのインストール |
