# 機能設計書 5-sp_BlitzLock

## 概要

本ドキュメントは、SQL Server First Responder Kitのsp_BlitzLockストアドプロシージャの機能設計について記載する。sp_BlitzLockはシステムヘルスセッションまたは拡張イベントからデッドロック情報を解析・出力する診断ツールである。

### 本機能の処理概要

sp_BlitzLockは、SQL Serverのシステムヘルスセッションまたはカスタム拡張イベントからデッドロック情報を抽出・解析し、デッドロックの原因特定と対策立案を支援するストアドプロシージャである。

**業務上の目的・背景**：デッドロックはアプリケーションのエラーやパフォーマンス低下を引き起こす重大な問題である。sp_BlitzLockは、複雑なデッドロックグラフXMLを解析し、関与するクエリ、オブジェクト、セッション情報を人間が理解しやすい形式で出力することで、迅速な問題解決を支援する。

**機能の利用シーン**：
- デッドロックエラー発生時の原因調査
- 定期的なデッドロック発生状況の監視
- アプリケーションのトランザクション設計見直し
- ロック競合パターンの分析

**主要な処理内容**：
1. 拡張イベントセッションからデッドロックXMLの抽出
2. デッドロックグラフXMLのパース
3. 関与プロセス・リソースの特定
4. 被害者（Victim）の識別
5. 詳細レポートの生成

**関連システム・外部連携**：
- システムヘルスセッション（system_health）
- カスタム拡張イベントセッション
- カスタムテーブルからのXML読み込み

**権限による制御**：
- VIEW SERVER STATE権限が必要
- 拡張イベントファイルへのアクセス権が必要（event_file使用時）

## 関連画面

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

## 機能種別

データ分析 / デッドロック診断 / トラブルシューティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| @DatabaseName | sysname | No | フィルタ対象データベース | NULL許可 |
| @StartDate | datetime | No | 検索開始日時 | NULL時は7日前 |
| @EndDate | datetime | No | 検索終了日時 | NULL時は現在 |
| @ObjectName | nvarchar(1024) | No | フィルタ対象オブジェクト | NULL許可 |
| @StoredProcName | nvarchar(1024) | No | フィルタ対象プロシージャ | NULL許可 |
| @AppName | sysname | No | フィルタ対象アプリケーション | NULL許可 |
| @HostName | sysname | No | フィルタ対象ホスト | NULL許可 |
| @LoginName | sysname | No | フィルタ対象ログイン | NULL許可 |
| @EventSessionName | sysname | No | 拡張イベントセッション名 | デフォルトsystem_health |
| @TargetSessionType | sysname | No | セッションタイプ（ring_buffer/event_file/table） | NULL時は自動検出 |
| @VictimsOnly | bit | No | 被害者のみ表示 | デフォルト0 |
| @DeadlockType | nvarchar(20) | No | デッドロックタイプ（regular/parallel） | NULL許可 |
| @TargetDatabaseName | sysname | No | テーブルソース時のDB名 | NULL許可 |
| @TargetSchemaName | sysname | No | テーブルソース時のスキーマ名 | デフォルトdbo |
| @TargetTableName | sysname | No | テーブルソース時のテーブル名 | NULL許可 |
| @TargetColumnName | sysname | No | XMLカラム名 | NULL許可 |
| @TargetTimestampColumnName | sysname | No | タイムスタンプカラム名 | NULL許可 |
| @Debug | bit | No | デバッグモード | デフォルト0 |
| @Help | bit | No | ヘルプ表示 | デフォルト0 |
| @OutputDatabaseName | sysname | No | 出力先データベース | NULL許可 |
| @OutputSchemaName | sysname | No | 出力先スキーマ | デフォルトdbo |
| @OutputTableName | sysname | No | 出力先テーブル | デフォルトBlitzLock |
| @ExportToExcel | bit | No | Excel出力用フォーマット | デフォルト0 |
| @Version | varchar(30) | No | バージョン（OUTPUT） | 出力専用 |
| @VersionDate | datetime | No | バージョン日付（OUTPUT） | 出力専用 |

### 入力データソース

- sys.dm_xe_session_targets: 拡張イベントターゲット
- sys.fn_xe_file_target_read_file: イベントファイル読み込み
- システムヘルスセッションのリングバッファ
- カスタムテーブル（@TargetTableName指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| deadlock_xml | xml | デッドロックグラフXML |
| event_date | datetime | イベント発生日時 |
| database_name | sysname | データベース名 |
| object_name | nvarchar(1000) | 関与オブジェクト |
| finding_group | nvarchar(100) | 発見グループ |
| finding | nvarchar(4000) | 発見内容 |
| victim | bit | 被害者フラグ |
| query_text | nvarchar(max) | 関与クエリテキスト |
| app_name | sysname | アプリケーション名 |
| host_name | sysname | ホスト名 |
| login_name | sysname | ログイン名 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証と初期化
   └─ 日付範囲、セッションタイプの設定

2. データソース決定
   └─ ring_buffer/event_file/tableから選択

3. デッドロックXML抽出
   └─ 拡張イベントまたはテーブルからXML取得

4. XMLパース
   └─ デッドロックグラフの構造解析

5. プロセス・リソース情報抽出
   └─ 被害者、加害者、ロックリソースの特定

6. フィルタリング
   └─ @DatabaseName等の条件でフィルタ

7. 結果出力
   └─ 結果セット返却またはテーブル出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ出力]
    C --> Z[終了]
    B -->|No| D[パラメータ初期化]
    D --> E{@TargetSessionType?}
    E -->|ring_buffer| F[リングバッファから読み込み]
    E -->|event_file| G[ファイルから読み込み]
    E -->|table| H[テーブルから読み込み]
    E -->|NULL| I[自動検出]
    I --> F
    F --> J[XMLパース]
    G --> J
    H --> J
    J --> K[プロセス・リソース抽出]
    K --> L[フィルタリング]
    L --> M[結果出力]
    M --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト期間 | @StartDate未指定時は7日前から | @StartDate=NULL |
| BR-002 | 日付検証 | @StartDateは@EndDate以前 | 常時 |
| BR-003 | MIデフォルト | Managed Instance時はring_bufferをデフォルト | MI環境 |
| BR-004 | テーブルソース検証 | テーブル使用時はテーブル・カラム存在確認 | @TargetSessionType='table' |
| BR-005 | XMLカラム検証 | @TargetColumnNameはXML型必須 | @TargetSessionType='table' |

### 計算ロジック

**UTC変換**:
```sql
@StartDateUTC = DATEADD(MINUTE, DATEDIFF(MINUTE, SYSDATETIME(), GETUTCDATE()), @StartDate)
@EndDateUTC = DATEADD(MINUTE, DATEDIFF(MINUTE, SYSDATETIME(), GETUTCDATE()), @EndDate)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 参照 | sys.dm_xe_session_targets | SELECT | XEターゲット情報取得 |
| 参照 | sys.fn_xe_file_target_read_file | SELECT | イベントファイル読み込み |
| 参照 | カスタムテーブル | SELECT | XML取得（テーブルソース時） |
| 挿入 | BlitzLock | INSERT | 結果出力（オプション） |
| 挿入 | BlitzLockFindings | INSERT | 発見事項出力（オプション） |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | deadlock_xml | 拡張イベントから抽出 | デッドロックグラフ格納 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 日付エラー | @StartDate > @EndDate | RAISERRORでエラー通知、RETURN |
| - | DB不在 | @TargetDatabaseNameが存在しない | RAISERRORでエラー通知、RETURN |
| - | テーブル不在 | @TargetTableNameが存在しない | RAISERRORでエラー通知、RETURN |
| - | カラム型エラー | @TargetColumnNameがXML型でない | RAISERRORでエラー通知、RETURN |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 通常実行: 数秒から数十秒（デッドロック数に依存）
- 大量デッドロック時: XMLパースに時間がかかる可能性

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

- VIEW SERVER STATE権限が必要
- 拡張イベントファイルへのアクセス権が必要（event_file使用時）

## 備考

- バージョン: 8.29（2026年2月3日時点）
- SQL Server 2012以降対応
- 特殊文字を含むテーブル名のXMLパースでエラーが発生する可能性

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: #deadlock_dataにデッドロックXMLを格納し、パース後の結果を#deadlock_findingsに格納する。

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

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

**主要処理フロー**:
1. **40-43行目**: SET STATISTICS XML OFF、NOCOUNT ON、XACT_ABORT OFF、READ UNCOMMITTED設定
2. **45行目**: バージョン情報設定
3. **148-226行目**: 環境検出（Azure、MI、RDS）

#### Step 3: テーブルソース検証を理解する

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

**主要処理フロー**:
- **388-399行目**: データベース存在確認
- **401-428行目**: スキーマ・テーブル・カラム存在確認
- **448-468行目**: XMLカラム型検証

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

```
sp_BlitzLock
    │
    ├─ sys.dm_xe_session_targets (XEターゲット)
    │
    ├─ sys.fn_xe_file_target_read_file (イベントファイル)
    │
    ├─ カスタムテーブル (テーブルソース時)
    │
    └─ XMLパース処理
           ├─ プロセス情報抽出
           ├─ リソース情報抽出
           └─ 被害者識別
```

### データフロー図

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

パラメータ ──────────────────▶ パラメータ検証 ─────────────────▶ #deadlock_data
   │                              │                                   │
XEリングバッファ ────────────▶ XML抽出 ──────────────────────────▶ │
   │                              │                                   │
XEイベントファイル ──────────▶ XML抽出 ──────────────────────────▶ │
   │                              │                                   │
カスタムテーブル ────────────▶ XML取得 ──────────────────────────▶ │
                                  │                                   │
                            XMLパース ◀───────────────────────────────┘
                                  │
                                  ▼
                         #deadlock_findings
                                  │
                                  ▼
                         [結果セット/テーブル]
```

### 関連ファイル一覧

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