# 帳票設計書 6-sp_BlitzLock

## 概要

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

### 本帳票の処理概要

sp_BlitzLockは、システムヘルスセッションまたはカスタムExtended Eventsからデッドロック情報を解析し、詳細なレポートを出力するストアドプロシージャである。デッドロックXMLを解析し、関与したプロセス、リソース、クエリテキスト、待機タイプなどの情報を可読性の高い形式で表示する。

**業務上の目的・背景**：デッドロックはアプリケーションの応答性低下やトランザクション失敗の原因となる重大な問題である。本帳票は、DBAがデッドロックの発生状況を分析し、根本原因を特定してアプリケーションやインデックス設計を改善することを目的としている。

**帳票の利用シーン**：
- デッドロック発生後の原因調査
- 定期的なデッドロック監視
- アプリケーション改修前の分析
- インデックス設計の見直し
- 並行処理設計の検証

**主要な出力内容**：
1. event_date（発生日時）：デッドロック発生時刻
2. victim_process（被害者プロセス）：ロールバックされたプロセス
3. database_name（データベース名）：関連データベース
4. object_name（オブジェクト名）：関連テーブル/インデックス
5. query_text（クエリテキスト）：実行されていたSQL
6. lock_type（ロックタイプ）：ロックの種類
7. wait_type（待機タイプ）：待機の種類
8. deadlock_graph（デッドロックグラフ）：XML形式のグラフ

**帳票の出力タイミング**：
- ストアドプロシージャ `EXEC sp_BlitzLock` の手動実行時
- SQL Server Agentジョブによる定期実行時
- デッドロック発生アラート後の調査時

**帳票の利用者**：
- データベース管理者（DBA）
- アプリケーション開発者
- パフォーマンスエンジニア
- システムアーキテクト

## 帳票種別

デッドロック分析レポート / 問題調査帳票

## 利用画面

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

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | TABLE / テーブル書き込み |
| 用紙サイズ | N/A（結果セットとして出力） |
| 向き | N/A |
| ファイル名 | N/A（テーブル出力時は@OutputTableName指定） |
| 出力方法 | 結果セット返却 / テーブル書き込み |
| 文字コード | NVARCHAR（Unicode） |

### ターゲットセッションタイプ

| TargetSessionType | 説明 |
|-------------------|------|
| ring_buffer | メモリ内リングバッファから取得 |
| event_file | イベントファイルから取得 |
| table | 指定テーブルから取得 |
| NULL | 自動検出 |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット1: デッドロック詳細                                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  event_date | victim | database | object | query_text | lock_type | ...     │
│  ---------- | ------ | -------- | ------ | ---------- | --------- | ...     │
│  2026-02-19 | SPID55 | UserDB   | Orders | UPDATE ... | X         | ...     │
│  2026-02-18 | SPID72 | SalesDB  | Items  | SELECT ... | U         | ...     │
│    ...      |  ...   |   ...    |  ...   |    ...     |    ...    | ...     │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│  結果セット2: デッドロックサマリー（Findings）                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  check_id | database_name | object_name | finding_group | finding | ...     │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 出力カラム詳細

| No | 項目名 | 説明 | データ型 | 表示形式 |
|----|-------|------|----------|---------|
| 1 | event_date | デッドロック発生日時 | DATETIME | 日時 |
| 2 | database_name | データベース名 | NVARCHAR(256) | テキスト |
| 3 | object_name | オブジェクト名 | NVARCHAR(1000) | テキスト |
| 4 | query_text | クエリテキスト | NVARCHAR(MAX) | テキスト |
| 5 | lock_type | ロックタイプ | NVARCHAR(100) | テキスト |
| 6 | wait_type | 待機タイプ | NVARCHAR(100) | テキスト |
| 7 | victim_process | 被害者プロセス | NVARCHAR(100) | テキスト |
| 8 | app_name | アプリケーション名 | SYSNAME | テキスト |
| 9 | host_name | ホスト名 | SYSNAME | テキスト |
| 10 | login_name | ログイン名 | SYSNAME | テキスト |
| 11 | deadlock_graph | デッドロックグラフXML | XML | XML |

### Findings出力カラム

| No | 項目名 | 説明 | データ型 |
|----|-------|------|----------|
| 1 | check_id | チェックID | INT |
| 2 | database_name | データベース名 | NVARCHAR(256) |
| 3 | object_name | オブジェクト名 | NVARCHAR(1000) |
| 4 | finding_group | 検出グループ | NVARCHAR(100) |
| 5 | finding | 検出内容 | NVARCHAR(4000) |
| 6 | sort_order | ソート順 | BIGINT |

## 出力条件

### 入力パラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @Help | BIT | 0 | 1でヘルプ表示 |
| @DatabaseName | SYSNAME | NULL | 対象データベース |
| @StartDate | DATETIME | NULL | 検索開始日（デフォルト: 7日前） |
| @EndDate | DATETIME | NULL | 検索終了日（デフォルト: 現在） |
| @ObjectName | NVARCHAR(1024) | NULL | 対象オブジェクト（完全修飾名） |
| @StoredProcName | NVARCHAR(1024) | NULL | 対象ストアドプロシージャ |
| @AppName | SYSNAME | NULL | 対象アプリケーション |
| @HostName | SYSNAME | NULL | 対象ホスト |
| @LoginName | SYSNAME | NULL | 対象ログイン |
| @EventSessionName | SYSNAME | 'system_health' | XEセッション名 |
| @TargetSessionType | SYSNAME | NULL | ターゲットタイプ |
| @VictimsOnly | BIT | 0 | 被害者のみ表示 |
| @DeadlockType | NVARCHAR(20) | NULL | デッドロックタイプ（regular/parallel） |
| @Debug | BIT | 0 | デバッグモード |
| @OutputDatabaseName | SYSNAME | NULL | 出力先DB |
| @OutputSchemaName | SYSNAME | 'dbo' | 出力先スキーマ |
| @OutputTableName | SYSNAME | 'BlitzLock' | 出力先テーブル |
| @ExportToExcel | BIT | 0 | Excel出力用フォーマット |

### テーブルソースパラメータ

| パラメータ名 | データ型 | デフォルト値 | 説明 |
|-------------|----------|-------------|------|
| @TargetDatabaseName | SYSNAME | NULL | XMLソーステーブルのDB |
| @TargetSchemaName | SYSNAME | NULL | XMLソーステーブルのスキーマ |
| @TargetTableName | SYSNAME | NULL | XMLソーステーブル名 |
| @TargetColumnName | SYSNAME | NULL | XML列名 |
| @TargetTimestampColumnName | SYSNAME | NULL | 日時列名（フィルタ用） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | event_date | 降順 |

### 改ページ条件

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

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

### 参照テーブル/DMV一覧

| テーブル/DMV名 | 用途 | 結合条件 |
|---------------|------|---------|
| sys.dm_xe_session_targets | XEセッションターゲット | event_session_id |
| sys.dm_xe_sessions | XEセッション | name |
| sys.fn_xe_file_target_read_file | イベントファイル読み取り | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 日時変換 | UTC→ローカル時刻変換 | - | DATEADD(MINUTE, DATEDIFF(...)) |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[sp_BlitzLock実行] --> B{@Help = 1?}
    B -->|Yes| C[ヘルプ表示して終了]
    B -->|No| D{@StartDate > @EndDate?}
    D -->|Yes| E[エラー: 日付範囲不正]
    D -->|No| F{@TargetSessionType判定}
    F -->|table| G[テーブルからXML取得]
    F -->|ring_buffer| H[リングバッファからXML取得]
    F -->|event_file| I[イベントファイルからXML取得]
    F -->|NULL| J[自動検出]
    G --> K[XMLをパース]
    H --> K
    I --> K
    J --> K
    K --> L[#deadlock_dataに格納]
    L --> M[詳細情報抽出]
    M --> N[フィルター適用]
    N --> O[Findings生成]
    O --> P{@OutputTableName?}
    P -->|Yes| Q[テーブルに出力]
    P -->|No| R[結果セット返却]
    Q --> S[終了]
    R --> S
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 日付範囲エラー | @StartDate > @EndDate | @StartDate cannot be after @EndDate | 日付順序を修正 |
| テーブル未存在 | @TargetTableNameが存在しない | The specified @TargetTableName does not exist | テーブル名を確認 |
| カラム未存在 | @TargetColumnNameが存在しない | The specified @TargetColumnName does not exist | カラム名を確認 |
| XML型エラー | @TargetColumnNameがXML型でない | must be of XML data type | XML型のカラムを指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | デッドロック発生数（通常0-100件/週） |
| 目標出力時間 | 30秒以内（7日間のデータ） |
| 同時出力数上限 | 制限なし |

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

- VIEW SERVER STATE権限が必要
- クエリテキストには機密情報が含まれる可能性あり
- ログイン名、ホスト名等の接続情報が出力される
- system_healthセッションへのアクセスが必要

## 備考

- バージョン: 8.29（2026年2月3日リリース）
- ライセンス: MIT License
- 公式サイト: http://FirstResponderKit.org
- SQL Server 2012以降対応
- Azure SQL Database/Managed Instance対応

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: XMLパース処理が複雑なため、まずデータ格納構造を把握すること。

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

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

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

**主要処理フロー**:
1. **行45**: バージョン情報の設定
2. **行52-146**: @Help=1の場合のヘルプ出力
3. **行273-334**: @StartDate/@EndDateのデフォルト設定とUTC変換

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

各ターゲットタイプからのXML取得処理を確認。

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

**主要処理フロー**:
- ring_buffer: sys.dm_xe_session_targetsから取得
- event_file: sys.fn_xe_file_target_read_fileから取得
- table: 指定テーブルからSELECT

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

```
sp_BlitzLock (エントリーポイント)
    │
    ├─ パラメータヘルプ表示 (@Help = 1)
    │
    ├─ パラメータ検証
    │      ├─ 日付範囲チェック
    │      ├─ テーブルソース検証（@TargetSessionType = 'table'時）
    │      └─ セッションタイプ自動検出
    │
    ├─ 一時テーブル作成
    │      ├─ #x (XML格納)
    │      ├─ #deadlock_data (パース済みXML)
    │      ├─ #t (ID格納)
    │      └─ #deadlock_findings (Findings)
    │
    ├─ XMLデータ取得
    │      ├─ ring_buffer
    │      ├─ event_file
    │      └─ table
    │
    ├─ XMLパース処理
    │      ├─ プロセス情報抽出
    │      ├─ リソース情報抽出
    │      └─ 待機情報抽出
    │
    └─ 結果出力
           ├─ デッドロック詳細
           └─ Findings
```

### データフロー図

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

system_health XE ──────▶ sp_BlitzLock ──────▶ デッドロック詳細
     or                        │                        │
event_file ◀───────────────────┤                        ├──▶ Findings
     or                        │                        │
カスタムテーブル ◀─────────────┘                        └──▶ 出力テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sp_BlitzLock.sql | `sp_BlitzLock.sql` | ソース | メインストアドプロシージャ |
| Install-All-Scripts.sql | `Install-All-Scripts.sql` | スクリプト | 全スクリプトのインストール |
