# 画面設計書 10-sp_BlitzLock 結果画面

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzLockストアドプロシージャが出力する、デッドロック分析結果画面の設計仕様を記載する。

### 本画面の処理概要

sp_BlitzLock結果画面は、System Healthセッションまたはカスタム拡張イベントからデッドロック情報を解析し、構造化された形式で表示する画面である。デッドロックのXML情報を解析し、関係するプロセス、リソース、クエリテキストを分かりやすく表示する。

**業務上の目的・背景**：デッドロックはSQL Serverでよく発生する問題の一つであり、アプリケーションのエラーやパフォーマンス低下の原因となる。SQL Serverはデッドロック情報をSystem Health拡張イベントセッションに自動的に記録するが、生のXMLデータを解読するのは困難である。sp_BlitzLockは、このXMLを解析し、デッドロックの原因（どのプロセスがどのリソースをロックしていたか、どのクエリが関係していたか）を分かりやすく表示する。これにより、DBAはデッドロックの根本原因を特定し、アプリケーションやインデックスの改善を行える。

**画面へのアクセス方法**：SQL Server Management Studio (SSMS)またはAzure Data Studioなどのクエリツールから、`EXEC sp_BlitzLock`を実行することで結果画面にアクセスする。@StartDate/@EndDateで分析期間を、@DatabaseNameでフィルタリングが可能。

**主要な操作・処理内容**：
1. System Healthセッション（またはカスタムXEセッション）からデッドロックXMLを取得
2. XMLを解析し、各デッドロックイベントの詳細を抽出
3. プロセス情報、リソース情報、クエリテキストを構造化
4. フィルタ条件（日付、データベース、アプリケーション等）に基づき絞り込み
5. 結果を表示またはテーブルに出力

**画面遷移**：
- この画面から遷移できる画面：なし（デッドロック分析専用）
- この画面に遷移してくる画面：sp_BlitzFirst診断結果画面（ブロッキング検出時）

**権限による表示制御**：VIEW SERVER STATE権限が必要。System Health拡張イベントへのアクセスにはサーバーレベルの権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | sp_BlitzLock | 主機能 | System Healthセッションまたはカスタム拡張イベントからデッドロックを解析・表示 |

## 画面種別

一覧（デッドロック分析結果表示）

## URL/ルーティング

```sql
-- 基本実行（過去7日間のデッドロック）
EXEC sp_BlitzLock;

-- 日付範囲を指定
EXEC sp_BlitzLock
    @StartDate = '2024-01-01',
    @EndDate = '2024-01-31';

-- 特定データベースのみ
EXEC sp_BlitzLock @DatabaseName = 'MyDatabase';

-- 特定アプリケーションでフィルタ
EXEC sp_BlitzLock @AppName = 'MyApp';

-- カスタムXEセッションを使用
EXEC sp_BlitzLock @EventSessionName = 'MyDeadlockSession';

-- 結果をテーブルに出力
EXEC sp_BlitzLock
    @OutputDatabaseName = 'DBAtools',
    @OutputSchemaName = 'dbo',
    @OutputTableName = 'BlitzLock';

-- テーブルからXMLを読み込み
EXEC sp_BlitzLock
    @TargetDatabaseName = 'DBAtools',
    @TargetSchemaName = 'dbo',
    @TargetTableName = 'DeadlockXML',
    @TargetColumnName = 'DeadlockGraph';
```

## 入出力項目

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|---------|-------------|------|
| @DatabaseName | sysname | NULL | 特定データベースでフィルタ |
| @StartDate | datetime | NULL | 開始日時（デフォルト: 7日前） |
| @EndDate | datetime | NULL | 終了日時（デフォルト: 現在） |
| @ObjectName | nvarchar(1024) | NULL | 特定オブジェクト（Database.Schema.Table）でフィルタ |
| @StoredProcName | nvarchar(1024) | NULL | 特定ストアドプロシージャでフィルタ |
| @AppName | sysname | NULL | アプリケーション名でフィルタ |
| @HostName | sysname | NULL | ホスト名でフィルタ |
| @LoginName | sysname | NULL | ログイン名でフィルタ |
| @EventSessionName | sysname | 'system_health' | 拡張イベントセッション名 |
| @TargetSessionType | sysname | NULL | セッションタイプ（ring_buffer/event_file/table） |
| @VictimsOnly | bit | 0 | 犠牲者プロセスのみ表示 |
| @DeadlockType | nvarchar(20) | NULL | デッドロックタイプ（regular/parallel） |
| @OutputDatabaseName | sysname | NULL | 出力先データベース |
| @OutputSchemaName | sysname | 'dbo' | 出力先スキーマ |
| @OutputTableName | sysname | 'BlitzLock' | 出力先テーブル |
| @TargetDatabaseName | sysname | NULL | XMLソーステーブルのDB |
| @TargetSchemaName | sysname | NULL | XMLソーステーブルのスキーマ |
| @TargetTableName | sysname | NULL | XMLソーステーブル名 |
| @TargetColumnName | sysname | NULL | XML列名 |
| @TargetTimestampColumnName | sysname | NULL | タイムスタンプ列名 |
| @ExportToExcel | bit | 0 | Excel出力用フォーマット |
| @Debug | bit | 0 | デバッグモード |
| @Help | bit | 0 | ヘルプ表示 |

## 表示項目

### 結果セット

| 列名 | データ型 | 説明 |
|-----|---------|------|
| deadlock_id | INT | デッドロックの識別番号 |
| event_date | datetime | デッドロック発生日時 |
| deadlock_type | nvarchar(20) | デッドロックタイプ（Regular/Parallel） |
| database_name | sysname | データベース名 |
| spid | INT | プロセスID |
| is_victim | bit | 犠牲者かどうか |
| log_used | bigint | 使用ログサイズ |
| wait_resource | nvarchar(500) | 待機リソース |
| wait_type | nvarchar(100) | 待機タイプ |
| object_name | nvarchar(1024) | オブジェクト名 |
| index_name | nvarchar(256) | インデックス名 |
| lock_mode | nvarchar(50) | ロックモード |
| owner_mode | nvarchar(50) | 所有者モード |
| query_text | nvarchar(MAX) | クエリテキスト |
| transaction_count | INT | トランザクション数 |
| client_app | nvarchar(256) | クライアントアプリケーション |
| host_name | nvarchar(256) | ホスト名 |
| login_name | nvarchar(256) | ログイン名 |
| isolation_level | nvarchar(50) | 分離レベル |
| deadlock_graph | xml | デッドロックグラフXML |

### デッドロックタイプ

| タイプ | 説明 |
|-------|------|
| Regular | 通常のデッドロック（リソース競合） |
| Parallel | 並列クエリによるデッドロック |

### ロックモード

| モード | 説明 |
|-------|------|
| S | 共有ロック |
| X | 排他ロック |
| U | 更新ロック |
| IS | インテント共有 |
| IX | インテント排他 |
| SIX | 共有インテント排他 |

## イベント仕様

### 1-プロシージャ実行

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

1. パラメータの検証とデフォルト値の設定
2. XEセッションタイプの自動検出（ring_buffer/event_file）
3. デッドロックXMLの取得
4. XMLの解析と構造化
5. フィルタ条件の適用
6. 結果の返却（または出力テーブルへの保存）

### 2-XEセッションタイプ

| @TargetSessionType | データソース |
|-------------------|-------------|
| ring_buffer | メモリ内リングバッファ |
| event_file | ファイルベースのイベント |
| table | ユーザー指定のテーブル |
| NULL | 自動検出 |

### 3-Findings結果セット

メイン結果に加えて、デッドロック分析のサマリー（Findings）も出力される：

| 項目 | 説明 |
|-----|------|
| デッドロック件数 | 分析期間内のデッドロック総数 |
| 最頻出オブジェクト | 最も多くデッドロックに関与したオブジェクト |
| 最頻出アプリケーション | 最も多くデッドロックを発生させたアプリ |
| 推奨対応 | デッドロック解消のための推奨事項 |

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プロシージャ実行 | #deadlock_data | INSERT | デッドロックXMLを一時格納 |
| プロシージャ実行 | #deadlock_findings | INSERT | 分析結果を一時格納 |
| 出力テーブル指定時 | @OutputTableName | INSERT | 結果を永続テーブルに保存 |
| 出力テーブル指定時 | BlitzLockFindings | INSERT | Findings結果を保存 |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | deadlock_xml | XEセッションから取得 | XML型 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | エラー | @StartDate cannot be after @EndDate. | 日付範囲が不正な場合 |
| - | エラー | When using a table as a source, you must specify... | テーブルソース使用時のパラメータ不足 |
| - | エラー | The specified @TargetDatabaseName does not exist. | 指定DBが存在しない場合 |
| - | エラー | The specified @TargetColumnName must be of XML data type. | XML型でない列を指定した場合 |

## 例外処理

| 例外状況 | 動作 |
|---------|------|
| @StartDate > @EndDate | エラーメッセージを表示して終了 |
| デッドロック情報なし | 空の結果セットを返却 |
| System Healthセッションにアクセス不可 | エラーを返却 |
| XMLパースエラー | 問題のあるXMLをスキップして続行 |
| テーブルソースの列が存在しない | エラーメッセージを表示して終了 |

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 既知の制限事項：
  - SQL Server 2012以降のみ対応
  - テーブル名に特殊文字（XMLエンティティ参照）が含まれる場合、パースエラーの可能性
  - Azure Managed Instanceでは@TargetSessionType = 'ring_buffer'がデフォルト

---

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

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

### 推奨読解順序

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

デッドロックXMLを格納する一時テーブル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行238-250: #deadlock_dataテーブル定義 |
| 1-2 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行259-268: #deadlock_findingsテーブル定義 |

**読解のコツ**: デッドロックグラフはXML形式で保存される。XQueryを使用してXMLから必要な情報を抽出している。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行7-36: ALTER PROCEDUREとパラメータ定義 |
| 2-2 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行45-50: バージョン情報とVersionCheckMode処理 |
| 2-3 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行52-146: @Help処理 |

**主要処理フロー**:
1. **行45**: バージョン設定 `@Version = '8.29', @VersionDate = '20260203'`
2. **行18**: @EventSessionNameデフォルト値 'system_health'
3. **行273-334**: @StartDate/@EndDateのデフォルト設定（7日前〜現在）

#### Step 3: XMLソース検証を理解する

テーブルからXMLを取得する場合の検証処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sp_BlitzLock.sql | `sp_BlitzLock.sql` | 行357-500: テーブルソースの検証処理 |

**主要処理フロー**:
- **行388-399**: ターゲットデータベースの存在確認
- **行448-468**: XML列の型検証

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

```
sp_BlitzLock
    │
    ├─ パラメータ検証・初期化
    │      ├─ バージョンチェック
    │      ├─ @Help処理
    │      ├─ @StartDate/@EndDateデフォルト設定
    │      └─ テーブルソース検証（使用時）
    │
    ├─ XEセッションタイプ検出
    │      ├─ ring_buffer
    │      ├─ event_file
    │      └─ table
    │
    ├─ デッドロックXML取得
    │      └─ #deadlock_dataへINSERT
    │
    ├─ XML解析・構造化
    │      ├─ プロセス情報抽出
    │      ├─ リソース情報抽出
    │      └─ クエリテキスト抽出
    │
    ├─ フィルタ適用
    │      ├─ @DatabaseName
    │      ├─ @AppName
    │      ├─ @HostName
    │      └─ @LoginName
    │
    └─ 結果出力
           ├─ メイン結果セット
           └─ Findings結果セット
```

### データフロー図

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

System Health ──────────▶ sp_BlitzLock ─────────────▶ デッドロック
(ring_buffer/event_file)       │                        分析結果
        or                     ▼
ユーザーテーブル         #deadlock_data ───────────▶ Findings
                              │
                              ▼
                    XQuery解析 → フィルタ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzLock.sql | `sp_BlitzLock.sql` | ソース | メインプロシージャ定義 |
