# バッチ設計書 8-sp_BlitzAnalysis

## 概要

本ドキュメントは、SQL Server First Responder Kitに含まれるsp_BlitzAnalysisストアドプロシージャのバッチ設計書です。sp_BlitzAnalysisはBlitzFirst、BlitzCache、BlitzWhoの出力テーブルを分析し、時系列でパフォーマンス問題を可視化するツールです。

### 本バッチの処理概要

sp_BlitzAnalysisは、過去に収集されたsp_BlitzFirst、sp_BlitzCache、sp_BlitzWhoの出力データを統合分析し、指定された期間のパフォーマンス傾向を可視化するストアドプロシージャです。

**業務上の目的・背景**：リアルタイムの診断ツール（sp_BlitzFirst等）は「今、何が起きているか」を把握するのに有効ですが、「過去に何が起きていたか」を分析するには、蓄積されたデータを横断的に見る必要があります。sp_BlitzAnalysisは、定期的にテーブルに保存されたsp_BlitzFirst等の出力を時系列で分析し、パフォーマンス問題の傾向、繰り返しパターン、特定時間帯の問題を特定します。これにより、事後分析や傾向把握が可能になります。

**バッチの実行タイミング**：過去のデータ分析が必要な際に随時実行。障害報告の調査、週次/月次のパフォーマンスレビュー、問題の傾向分析時に使用されます。

**主要な処理内容**：
1. 指定期間内のBlitzFirst結果の集計・分析
2. 待機統計のデルタ分析
3. ファイルI/O統計のレイテンシ分析
4. Perfmonカウンターの時系列分析
5. BlitzCacheのクエリパフォーマンス分析
6. BlitzWhoの実行履歴分析
7. 結果の出力

**前後の処理との関連**：sp_BlitzFirst、sp_BlitzCache、sp_BlitzWhoの出力テーブルが事前に作成・蓄積されていることが前提です。これらのツールを定期実行してデータを蓄積した後、sp_BlitzAnalysisで分析を行います。

**影響範囲**：読み取り専用の分析ツールです。指定されたデータベースの出力テーブルからデータを読み取るのみで、データを変更しません。

## バッチ種別

診断・分析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| SQL Serverバージョン | SQL Server 2008以降 |
| 必要権限 | 出力テーブルへの読み取り権限 |
| 依存オブジェクト | sp_BlitzFirst/BlitzCache/BlitzWhoの出力テーブル |

### 実行可否判定

- @OutputDatabaseNameで指定されたデータベースが存在すること
- 各出力テーブルが存在すること（存在しない場合はスキップ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| @Help | TINYINT | No | 0 | ヘルプ表示 |
| @StartDate | DATETIMEOFFSET(7) | No | NULL | 分析開始日時（NULLで1時間前） |
| @EndDate | DATETIMEOFFSET(7) | No | NULL | 分析終了日時（NULLで@StartDate+1時間） |
| @OutputDatabaseName | NVARCHAR(256) | No | 'DBAtools' | 出力テーブルがあるDB |
| @OutputSchemaName | NVARCHAR(256) | No | 'dbo' | 出力テーブルのスキーマ |
| @OutputTableNameBlitzFirst | NVARCHAR(256) | No | 'BlitzFirst' | BlitzFirst出力テーブル |
| @OutputTableNameFileStats | NVARCHAR(256) | No | 'BlitzFirst_FileStats' | ファイル統計テーブル |
| @OutputTableNamePerfmonStats | NVARCHAR(256) | No | 'BlitzFirst_PerfmonStats' | Perfmonテーブル |
| @OutputTableNameWaitStats | NVARCHAR(256) | No | 'BlitzFirst_WaitStats' | 待機統計テーブル |
| @OutputTableNameBlitzCache | NVARCHAR(256) | No | 'BlitzCache' | BlitzCache出力テーブル |
| @OutputTableNameBlitzWho | NVARCHAR(256) | No | 'BlitzWho' | BlitzWho出力テーブル |
| @Servername | NVARCHAR(128) | No | @@SERVERNAME | 対象サーバー名 |
| @Databasename | NVARCHAR(128) | No | NULL | フィルタ用データベース名 |
| @BlitzCacheSortorder | NVARCHAR(20) | No | 'cpu' | BlitzCacheソート順 |
| @MaxBlitzFirstPriority | INT | No | 249 | BlitzFirst最大優先度 |
| @ReadLatencyThreshold | INT | No | 100 | 読み取りレイテンシ閾値（ms） |
| @WriteLatencyThreshold | INT | No | 100 | 書き込みレイテンシ閾値（ms） |
| @WaitStatsTop | TINYINT | No | 10 | 待機統計のTop件数 |
| @Version | VARCHAR(30) | No | NULL | バージョン（OUTPUT） |
| @VersionDate | DATETIME | No | NULL | バージョン日付（OUTPUT） |
| @VersionCheckMode | BIT | No | 0 | バージョンチェックモード |
| @BringThePain | BIT | No | 0 | 長時間分析の許可 |
| @Maxdop | INT | No | 1 | 最大並列度 |
| @Debug | BIT | No | 0 | デバッグモード |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| BlitzFirst | テーブル | BlitzFirst出力 |
| BlitzFirst_FileStats_Deltas | ビュー | ファイル統計デルタ |
| BlitzFirst_PerfmonStats_Actuals | ビュー | Perfmonアクチュアル |
| BlitzFirst_WaitStats_Deltas | ビュー | 待機統計デルタ |
| BlitzCache | テーブル | BlitzCache出力 |
| BlitzWho_Deltas | ビュー | BlitzWhoデルタ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 結果セット1 | TABLE | レポート期間情報 |
| 結果セット2 | TABLE | BlitzFirst検出結果集計 |
| 結果セット3 | TABLE | BlitzFirst詳細 |
| 結果セット4 | TABLE | 待機統計 |
| 結果セット5 | TABLE | ファイル統計 |
| 結果セット6 | TABLE | Perfmon統計 |
| 結果セット7 | TABLE | BlitzCache結果 |
| 結果セット8 | TABLE | BlitzWho結果 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | 画面出力 |
| 文字コード | UTF-16 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ データベース存在チェック、日付範囲設定
2. BlitzFirst分析
   └─ 検出結果の集計、優先度別カウント
3. 待機統計分析
   └─ デルタビューからのTop待機取得
4. ファイル統計分析
   └─ レイテンシ閾値超過のチェック
5. Perfmon分析
   └─ アクチュアル値の時系列表示
6. BlitzCache分析
   └─ ソート順でのクエリ取得
7. BlitzWho分析
   └─ デルタビューからの履歴取得
8. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[パラメータ検証]
    B --> C{@OutputDatabaseName存在?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[BlitzFirst分析]
    E --> F[待機統計分析]
    F --> G[ファイル統計分析]
    G --> H[Perfmon分析]
    H --> I[BlitzCache分析]
    I --> J[BlitzWho分析]
    J --> K[結果出力]
    K --> L[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| データ取得 | BlitzFirst | SELECT | 検出結果取得 |
| データ取得 | BlitzFirst_WaitStats_Deltas | SELECT | 待機統計取得 |
| データ取得 | BlitzFirst_FileStats_Deltas | SELECT | ファイル統計取得 |
| データ取得 | BlitzCache | SELECT | クエリ分析結果取得 |
| データ取得 | BlitzWho_Deltas | SELECT | プロセス履歴取得 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | Priority, FindingsGroup, Finding, TotalOccurrences | BlitzFirstからの集計 | 検出結果カウント |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | データベースエラー | @OutputDatabaseNameが存在しない | 正しいDB名を指定 |
| - | ソート順エラー | 無効な@BlitzCacheSortorder | 有効な値を指定 |
| - | 時間範囲エラー | @BringThePain=0で4時間超 | @BringThePain=1を指定 |

### リトライ仕様

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

### 障害時対応

- テーブルが存在しない場合はスキップして続行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | READ UNCOMMITTED（暗黙的） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 分析期間のレコード数 |
| 目標処理時間 | 数秒〜数分 |
| メモリ使用量上限 | 環境依存 |

## 排他制御

- 読み取り専用のため排他制御不要

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | @StartDate/EndDate設定時 | 'Setting @StartDate to: 1 hour ago'等 |
| 進捗ログ | 各ステップ | 'Getting BlitzFirst info from...'等 |
| デバッグログ | @Debug=1時 | 実行SQL文 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 特記事項:
  - @StartDate=NULLで1時間前から分析
  - @BlitzCacheSortorderは'all','cpu','reads','writes','duration','executions','memory grant','spills'をサポート
  - @BringThePain=1で4時間以上の分析が可能
  - @Maxdop=1がデフォルト（並列度制限）
  - テーブルが存在しない場合はスキップして続行
