# 画面設計書 148-待機統計

## 概要

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

### 本画面の処理概要

SQL Serverのsys.dm_os_wait_statsから待機統計を取得・分析し、パフォーマンスボトルネックやリソース競合問題を特定する機能を提供する。待機タイプの分類、タイミングメトリクスと割合の計算、Paul Randalの方法論に基づく診断説明を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を診断する際、待機統計はシステムがどのようなリソース（ディスクI/O、メモリ、ロック、CPU等）で待機しているかを示す重要な指標である。本機能を使用することで、パフォーマンスボトルネックの原因を特定し、適切な対策を講じることができる。

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

**主要な操作・処理内容**：
1. 待機統計取得（Get-DbaWaitStatistic）：sys.dm_os_wait_statsから待機統計を取得し、カテゴリ分類と診断情報を付加
2. 待機統計クリア（Clear-DbaWaitStatistics）：DBCC SQLPERFで待機統計をリセット

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 280 | Get-DbaWaitStatistic | 主機能 | 待機統計の取得・分析 |
| 55 | Clear-DbaWaitStatistics | 主機能 | 待機統計のクリア |

## 画面種別

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

## URL/ルーティング

```powershell
# 待機統計の取得
Get-DbaWaitStatistic -SqlInstance sql01

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

# 無視可能な待機タイプも含めて取得
Get-DbaWaitStatistic -SqlInstance sql01 -IncludeIgnorable

# 詳細情報を表示
Get-DbaWaitStatistic -SqlInstance sql01 | Select-Object *

# 待機統計をクリア
Clear-DbaWaitStatistics -SqlInstance sql01

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

## 入出力項目

### Get-DbaWaitStatistic パラメータ

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

### Clear-DbaWaitStatistics パラメータ

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

## 表示項目

### Get-DbaWaitStatistic 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| WaitType | string | 待機タイプ名（例：PAGEIOLATCH_EX, LCK_M_IX） |
| Category | string | 待機カテゴリ（Buffer IO, Lock, Network IO, CPU, Idle, Memory等） |
| WaitSeconds | decimal | 合計待機時間（秒） |
| ResourceSeconds | decimal | リソース待機時間（秒） |
| SignalSeconds | decimal | シグナル待機時間（秒） |
| WaitCount | bigint | 待機発生回数 |
| Percentage | decimal | 合計待機時間に対する割合（0-100） |
| AverageWaitSeconds | decimal | 平均待機時間（秒） |
| AverageResourceSeconds | decimal | 平均リソース待機時間（秒） |
| AverageSignalSeconds | decimal | 平均シグナル待機時間（秒） |
| URL | string | sqlskills.comの詳細ドキュメントへのリンク |
| Notes | string | 診断説明とトラブルシューティングガイダンス（Select-Object *で表示） |
| Ignorable | boolean | 無視可能な待機タイプかどうか（IncludeIgnorable時のみ） |

### Clear-DbaWaitStatistics 出力

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

## イベント仕様

### 1-待機統計取得

**Get-DbaWaitStatistic 実行時**

1. Connect-DbaInstanceでSQL Serverに接続
2. sys.dm_os_wait_statsを照会
3. 待機タイプごとにカテゴリを分類
4. 累積割合を計算し、Threshold以下の待機タイプを除外
5. IncludeIgnorable未指定時は無視可能な待機タイプを除外
6. 詳細メモ（Notes）を各待機タイプに付加
7. sqlskills.comへのURLを生成
8. Select-DefaultViewでデフォルト表示プロパティを設定

### 2-待機統計クリア

**Clear-DbaWaitStatistics 実行時**

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- SQL Server 2005以上が必要
- Thresholdは累積割合（デフォルト95%）で、待機時間の多い順に95%に達するまでの待機タイプを返す
- 無視可能な待機タイプには、Service Brokerアイドル待機、バックグラウンドタスク待機などが含まれる
- 待機タイプのカテゴリ分類はBrent Ozar、Marcin Gminskiの情報に基づく
- 診断メモはPaul Randalの方法論に基づく
- URLはsqlskills.comの待機タイプライブラリへのリンク

---

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

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

### 推奨読解順序

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

待機統計の出力構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaWaitStatistic.ps1 | `public/Get-DbaWaitStatistic.ps1` | 58-84行目: .OUTPUTSセクション |
| 1-2 | Clear-DbaWaitStatistics.ps1 | `public/Clear-DbaWaitStatistics.ps1` | 41-51行目: .OUTPUTSセクション |

**読解のコツ**: Get-DbaWaitStatisticの出力には、基本メトリクスに加えてCategory、Notesの診断情報が含まれる。

#### Step 2: 診断情報データを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaWaitStatistic.ps1 | `public/Get-DbaWaitStatistic.ps1` | 124-160行目: $details（診断メモ） |
| 2-2 | Get-DbaWaitStatistic.ps1 | `public/Get-DbaWaitStatistic.ps1` | 165-200行目以降: $category（カテゴリ分類） |

**主要処理フロー**:
- **124-160行目**: 各待機タイプの詳細診断メモ（Paul Randalの解説）
- **165行目以降**: 待機タイプからカテゴリへのマッピング（Brent Ozar/Marcin Gminskiのデータ）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaWaitStatistic.ps1 | `public/Get-DbaWaitStatistic.ps1` | 112-120行目: パラメータ定義 |
| 3-2 | Clear-DbaWaitStatistics.ps1 | `public/Clear-DbaWaitStatistics.ps1` | 63-70行目: パラメータ定義 |
| 3-3 | Clear-DbaWaitStatistics.ps1 | `public/Clear-DbaWaitStatistics.ps1` | 80-86行目: DBCC SQLPERFの実行 |

**主要処理フロー（Clear-DbaWaitStatistics）**:
- **75行目**: Connect-DbaInstance -MinimumVersion 9
- **80行目**: ShouldProcess確認
- **82行目**: DBCC SQLPERF (N'sys.dm_os_wait_stats', CLEAR)実行

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

```
Get-DbaWaitStatistic
    │
    ├─ Connect-DbaInstance (SQL Server接続)
    │
    ├─ $server.Query() (sys.dm_os_wait_stats照会)
    │
    ├─ [カテゴリ分類]
    │      └─ $category ハッシュテーブル参照
    │
    ├─ [累積割合計算]
    │      └─ Threshold フィルタリング
    │
    ├─ [無視可能フィルタ]
    │      └─ IncludeIgnorable スイッチ
    │
    ├─ [診断情報付加]
    │      ├─ $details ハッシュテーブル参照
    │      └─ URL生成 (sqlskills.com)
    │
    └─ Select-DefaultView (出力)

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

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ SMO Server
                              │
                              ▼
                     sys.dm_os_wait_stats
                     照会
                              │
                              ▼
                     カテゴリ分類
                     (Buffer IO, Lock, etc.)
                              │
                              ▼
                     累積割合計算                     PSCustomObject
                     Threshold フィルタ              │
                              │                      ├─ WaitType
                              ▼                      ├─ Category
                     [IncludeIgnorable]              ├─ WaitSeconds
                     無視可能フィルタ                 ├─ ResourceSeconds
                              │                      ├─ SignalSeconds
                              ▼                      ├─ WaitCount
                     診断情報付加                     ├─ Percentage
                     (Notes, URL)                   ├─ AverageWaitSeconds
                              │                      ├─ URL
                              ▼                      └─ Notes (Select *)
                     Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWaitStatistic.ps1 | `public/Get-DbaWaitStatistic.ps1` | ソース | 待機統計取得・分析 |
| Clear-DbaWaitStatistics.ps1 | `public/Clear-DbaWaitStatistics.ps1` | ソース | 待機統計クリア |
