# 画面設計書 149-ラッチ統計

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverラッチ統計（Latch Statistics）管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverのsys.dm_os_latch_statsからラッチ競合統計を取得・分析し、パフォーマンスボトルネックを特定する機能を提供する。Paul Randalの方法論に基づき、累積待機時間割合に基づいて最も重要なラッチクラスを返す。

**業務上の目的・背景**：ラッチはSQL Server内部でメモリページへの同時アクセスを制御するための軽量同期メカニズムである。ラッチ競合が発生すると、クエリパフォーマンスが低下する。本機能を使用することで、どのラッチクラスで競合が発生しているかを特定し、適切な対策を講じることができる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行する。
- `Get-DbaLatchStatistic` - ラッチ統計の取得
- `Clear-DbaLatchStatistics` - ラッチ統計のクリア

**主要な操作・処理内容**：
1. ラッチ統計取得（Get-DbaLatchStatistic）：sys.dm_os_latch_statsからラッチ統計を取得し、累積割合でフィルタリング
2. ラッチ統計クリア（Clear-DbaLatchStatistics）：DBCC SQLPERFでラッチ統計をリセット

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：VIEW SERVER STATE権限が必要。クリアにはALTER SERVER STATE権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 217 | Get-DbaLatchStatistic | 主機能 | ラッチ統計の取得・分析 |
| 52 | Clear-DbaLatchStatistics | 主機能 | ラッチ統計のクリア |

## 画面種別

コマンドラインインターフェース（CLI）/ PowerShell関数

## URL/ルーティング

```powershell
# ラッチ統計の取得
Get-DbaLatchStatistic -SqlInstance sql01

# 閾値を指定して取得
Get-DbaLatchStatistic -SqlInstance sql01 -Threshold 98

# 全ラッチクラスを取得
Get-DbaLatchStatistic -SqlInstance sql01 -Threshold 100

# ラッチ統計をクリア
Clear-DbaLatchStatistics -SqlInstance sql01

# 確認なしでクリア
Clear-DbaLatchStatistics -SqlInstance sql01 -Confirm:$false
```

## 入出力項目

### Get-DbaLatchStatistic パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Threshold | int | No | 累積割合閾値（デフォルト95%） |
| EnableException | switch | No | 例外処理モードの有効化 |

### Clear-DbaLatchStatistics パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| WhatIf | switch | No | 実行せずに動作を表示 |
| Confirm | switch | No | 確認プロンプトを表示 |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

### Get-DbaLatchStatistic 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| WaitType | string | ラッチクラス名（例：ACCESS_METHODS_LATCH_EX） |
| WaitSeconds | decimal | 合計待機時間（秒、小数点以下2桁） |
| WaitCount | bigint | 待機要求回数 |
| Percentage | decimal | 合計ラッチ待機時間に対する割合（0-100、小数点以下2桁） |
| AverageWaitSeconds | decimal | 平均待機時間（秒、小数点以下4桁） |
| URL | string | SQLSkillsのラッチクラスドキュメントへのリンク |

### Clear-DbaLatchStatistics 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Status | string | Success または 例外オブジェクト |

## イベント仕様

### 1-ラッチ統計取得

**Get-DbaLatchStatistic 実行時**

1. Connect-DbaInstanceでSQL Serverに接続（MinimumVersion 9）
2. sys.dm_os_latch_statsをCTE（Common Table Expression）で照会
3. BUFFERラッチクラスを除外
4. 累積待機時間割合でThreshold以下のラッチクラスを除外
5. 各ラッチクラスにSQLSkillsへのURLを生成
6. PSCustomObjectとして出力

### 2-ラッチ統計クリア

**Clear-DbaLatchStatistics 実行時**

1. Connect-DbaInstanceでSQL Serverに接続（MinimumVersion 9）
2. ShouldProcessで確認（ConfirmImpact = 'High'）
3. DBCC SQLPERF (N'sys.dm_os_latch_stats', CLEAR)を実行
4. 結果をPSCustomObjectで返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ラッチ統計取得 | sys.dm_os_latch_stats | SELECT | DMV読み取りのみ |
| ラッチ統計クリア | sys.dm_os_latch_stats | CLEAR | 統計リセット |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | エラー | "Failure" | SQL Server接続失敗 |
| MSG002 | 成功 | Status = "Success" | クリア成功 |
| MSG003 | 確認 | "Performing CLEAR of sys.dm_os_latch_stats" | クリア実行前確認 |

## 例外処理

| 例外条件 | 対応処理 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラー記録、Continueで次インスタンスへ |
| クリア実行失敗 | 例外オブジェクトをStatusに格納 |

## 備考

- SQL Server 2005以上が必要
- BUFFERラッチクラスは常に除外（バッファプール関連のラッチは大量に発生するため）
- Thresholdは累積割合（デフォルト95%）で、待機時間の多い順に95%に達するまでのラッチクラスを返す
- URLはsqlskills.comのラッチヘルプへのリンク（https://www.sqlskills.com/help/latches/{LatchClass}）
- Paul Randalの方法論に基づく分析手法を採用

---

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

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

### 推奨読解順序

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

ラッチ統計の出力構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaLatchStatistic.ps1 | `public/Get-DbaLatchStatistic.ps1` | 50-65行目: .OUTPUTSセクション |
| 1-2 | Clear-DbaLatchStatistics.ps1 | `public/Clear-DbaLatchStatistics.ps1` | 32-42行目: .OUTPUTSセクション |

**読解のコツ**: Get-DbaLatchStatisticはWaitType（ラッチクラス名）に加えてURLを提供し、各ラッチクラスのドキュメントに直接リンクする。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaLatchStatistic.ps1 | `public/Get-DbaLatchStatistic.ps1` | 109-131行目: $sqlクエリ定義 |

**主要処理フロー**:
- **111-119行目**: CTEでsys.dm_os_latch_statsからデータ取得
- **118行目**: BUFFERラッチを除外
- **115行目**: 累積割合を計算
- **131行目**: Thresholdでフィルタリング

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaLatchStatistic.ps1 | `public/Get-DbaLatchStatistic.ps1` | 99-106行目: パラメータ定義 |
| 3-2 | Get-DbaLatchStatistic.ps1 | `public/Get-DbaLatchStatistic.ps1` | 144-156行目: 出力オブジェクト生成 |
| 3-3 | Clear-DbaLatchStatistics.ps1 | `public/Clear-DbaLatchStatistics.ps1` | 93-106行目: クリア処理 |

**主要処理フロー**:
- **139行目**: Connect-DbaInstance -MinimumVersion 9
- **144行目**: $server.Query($sql)でクエリ実行
- **145-155行目**: PSCustomObject作成
- **95行目**: DBCC SQLPERF実行

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

```
Get-DbaLatchStatistic
    │
    ├─ Connect-DbaInstance -MinimumVersion 9
    │
    ├─ $server.Query()
    │      │
    │      └─ CTEクエリ
    │             ├─ sys.dm_os_latch_stats
    │             ├─ BUFFER除外
    │             ├─ 累積割合計算
    │             └─ Threshold フィルタ
    │
    └─ [foreach row]
           │
           ├─ WaitType = LatchClass
           ├─ WaitSeconds
           ├─ WaitCount
           ├─ Percentage
           ├─ AverageWaitSeconds
           └─ URL (sqlskills.com)

Clear-DbaLatchStatistics
    │
    ├─ Connect-DbaInstance -MinimumVersion 9
    │
    ├─ ShouldProcess (確認)
    │
    ├─ $server.Query()
    │      └─ DBCC SQLPERF (N'sys.dm_os_latch_stats', CLEAR)
    │
    └─ PSCustomObject (結果出力)
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ SMO Server
                              │
                              ▼
                     sys.dm_os_latch_stats
                     CTEクエリ
                              │
                              ├─ BUFFER除外
                              ├─ wait_time_ms計算
                              ├─ 累積割合計算
                              └─ ROW_NUMBER()
                              │
                              ▼
                     Threshold フィルタ              PSCustomObject
                     (HAVING句)                      │
                              │                      ├─ WaitType
                              ▼                      ├─ WaitSeconds
                     URL生成                         ├─ WaitCount
                     (sqlskills.com)                ├─ Percentage
                              │                      ├─ AverageWaitSeconds
                              ▼                      └─ URL
                     PSCustomObject出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaLatchStatistic.ps1 | `public/Get-DbaLatchStatistic.ps1` | ソース | ラッチ統計取得・分析 |
| Clear-DbaLatchStatistics.ps1 | `public/Clear-DbaLatchStatistics.ps1` | ソース | ラッチ統計クリア |
