# バッチ設計書 5-sp_BlitzLock

## 概要

本ドキュメントは、SQL Server First Responder Kitに含まれるsp_BlitzLockストアドプロシージャのバッチ設計書です。sp_BlitzLockはシステムヘルスセッションまたはカスタム拡張イベントからデッドロック情報を分析するツールです。

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

sp_BlitzLockは、SQL Serverで発生したデッドロックの情報を収集・分析し、デッドロックの原因となったプロセス、オブジェクト、クエリを特定するストアドプロシージャです。

**業務上の目的・背景**：デッドロックはSQL Serverにおいて最も troublesome な問題の一つです。アプリケーションのエラーやパフォーマンス低下の原因となり、根本原因の特定が困難な場合があります。sp_BlitzLockは、システムヘルスセッションやカスタム拡張イベントに記録されたデッドロックグラフを解析し、関与したプロセス、待機リソース、実行されていたクエリを視覚的にわかりやすく提示します。これにより、デッドロックの根本原因分析と解決策の策定を支援します。

**バッチの実行タイミング**：デッドロックエラーが報告された際に随時実行。または定期的に実行してデッドロックの傾向を監視します。

**主要な処理内容**：
1. システムヘルスセッションまたは指定された拡張イベントからデッドロックXMLを取得
2. デッドロックXMLの解析（プロセス、リソース、待機グラフ）
3. デッドロック参加者の情報抽出（クエリテキスト、オブジェクト名、ロックタイプ）
4. デッドロックの犠牲者と生存者の特定
5. デッドロックのパターン分析
6. 結果の出力とフィルタリング

**前後の処理との関連**：デッドロックの根本原因がインデックス問題の場合、sp_BlitzIndexで詳細分析を行います。クエリの問題の場合、sp_BlitzCacheでクエリ分析を行います。

**影響範囲**：読み取り専用の診断ツールです。システムヘルスセッションからXMLを読み取るため、大量のデッドロックが記録されている場合は実行時間が長くなる可能性があります。

## バッチ種別

診断・分析

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動/デッドロック発生時 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| SQL Serverバージョン | SQL Server 2012以降 |
| 必要権限 | VIEW SERVER STATE権限 |
| 依存オブジェクト | システムヘルスセッション（デフォルト） |

### 実行可否判定

- @StartDateが@EndDateより後の場合はエラー
- 指定されたイベントセッションが存在しない場合はエラー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| @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 | NULL | セッションタイプ（ring_buffer/event_file/table） |
| @VictimsOnly | bit | No | 0 | 犠牲者のみ表示 |
| @DeadlockType | nvarchar(20) | No | NULL | デッドロックタイプ（regular/parallel） |
| @TargetDatabaseName | sysname | No | NULL | XMLソーステーブルのDB |
| @TargetSchemaName | sysname | No | NULL | XMLソーステーブルのスキーマ |
| @TargetTableName | sysname | No | NULL | XMLソーステーブル名 |
| @TargetColumnName | sysname | No | NULL | XMLカラム名 |
| @TargetTimestampColumnName | sysname | No | NULL | タイムスタンプカラム名 |
| @Debug | bit | No | 0 | デバッグモード |
| @Help | bit | No | 0 | ヘルプ表示 |
| @Version | varchar(30) | No | NULL | バージョン（OUTPUT） |
| @VersionDate | datetime | No | NULL | バージョン日付（OUTPUT） |
| @VersionCheckMode | bit | No | 0 | バージョンチェックモード |
| @OutputDatabaseName | sysname | No | NULL | 出力先データベース |
| @OutputSchemaName | sysname | No | 'dbo' | 出力先スキーマ |
| @OutputTableName | sysname | No | 'BlitzLock' | 出力先テーブル |
| @ExportToExcel | bit | No | 0 | Excel出力用整形 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| sys.dm_xe_session_targets | DMV | 拡張イベントターゲット |
| system_health session | 拡張イベント | デッドロックXML |
| カスタムテーブル | テーブル | @Target*指定時のソース |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 結果セット | TABLE | デッドロック詳細 |
| BlitzLock | DB | @OutputDatabaseName指定時 |
| BlitzLockFindings | DB | 検出結果サマリー |

### 出力ファイル仕様

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

主要な出力カラム:
- event_date, deadlock_type, database_name
- object_name, index_name, lock_mode
- query_text, process_id, victim

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ 日付範囲チェック、セッションタイプ検証
2. デッドロックXML取得
   └─ システムヘルス/カスタムセッションから抽出
3. XML解析
   └─ デッドロックグラフのパース
4. プロセス情報抽出
   └─ 各参加プロセスの詳細取得
5. リソース情報抽出
   └─ ロック対象オブジェクトの特定
6. フィルタリング
   └─ 指定条件でのフィルタ適用
7. 結果出力
   └─ デッドロック詳細とサマリー
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[パラメータ検証]
    B --> C{日付範囲チェック}
    C -->|OK| D[デッドロックXML取得]
    C -->|NG| E[エラー終了]
    D --> F{ソース判定}
    F -->|system_health| G[リングバッファから取得]
    F -->|event_file| H[ファイルから取得]
    F -->|table| I[テーブルから取得]
    G & H & I --> J[XML解析]
    J --> K[プロセス情報抽出]
    K --> L[リソース情報抽出]
    L --> M[フィルタリング]
    M --> N{出力先判定}
    N -->|TABLE| O[画面出力]
    N -->|DB| P[テーブル出力]
    O & P --> Q[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| XML取得 | sys.dm_xe_session_targets | SELECT | デッドロックXML取得 |
| 結果保存 | BlitzLock | INSERT | デッドロック詳細 |
| 結果保存 | BlitzLockFindings | INSERT | 検出サマリー |

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

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

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | deadlock_xml | 拡張イベントから取得 | XML型 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 日付エラー | @StartDate > @EndDate | 正しい日付範囲を指定 |
| - | セッションエラー | 指定セッションが存在しない | system_healthを使用 |
| - | テーブルエラー | @Target*テーブルが存在しない | 正しいテーブル名を指定 |

### リトライ仕様

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

### 障害時対応

- デッドロックXMLに特殊文字が含まれる場合、パースエラーが発生する可能性あり

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | デッドロック数による |
| 目標処理時間 | 数秒〜数分 |
| メモリ使用量上限 | XML解析によりメモリ使用量増加の可能性 |

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | @Debug=1時 | 処理開始 |
| 進捗ログ | @Debug=1時 | 各ステップの状況 |
| 終了ログ | @Debug=1時 | 処理完了 |

## 監視・アラート

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

## 備考

- バージョン: 8.29（2026年2月3日）
- ライセンス: MIT License
- 既知の制限:
  - SQL Server 2012以降のみサポート
  - オブジェクト名に特殊文字が含まれる場合、XMLパースエラーの可能性
- 特記事項:
  - @VictimsOnly=1でデッドロック犠牲者のみ表示
  - @DeadlockType='parallel'で並列処理デッドロックをフィルタ
  - カスタムテーブルからのXML読み取りに対応
