# 画面設計書 154-待機タスク

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける待機タスク監視機能の設計を定義する。現在SQL Serverインスタンス上で待機中のセッションを特定し、待機タイプ、ブロッキング情報、SQLテキスト、クエリプランなどの詳細な診断情報を提供する。

### 本画面の処理概要

本機能は、sys.dm_os_waiting_tasksと関連DMVを照会し、リアルタイムの待機状況を分析するための包括的な情報を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を調査する際、「何が待っているのか」を把握することは最も基本的な診断ステップである。本機能は、Paul Randalの待機タスクスクリプトに基づき、待機中のセッションを特定し、待機タイプ、待機時間、ブロッキングセッション、実行中のSQLテキストとクエリプランを一覧で取得できる。CXPACKETなどの並列処理待機についてはDOP情報も含まれる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaWaitingTask -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. sys.dm_os_waiting_tasksから待機中タスクを取得
2. sys.dm_os_tasks、sys.dm_exec_sessions、sys.dm_exec_requestsとの結合
3. sys.dm_exec_query_memory_grantsからDOP情報取得（CXPACKET待機用）
4. sys.dm_exec_sql_textでSQLテキスト取得
5. sys.dm_exec_query_planでクエリプラン取得
6. SQLSkillsの待機タイプドキュメントへのURL生成

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- InfoUrlプロパティからSQLSkillsの待機タイプドキュメントへ遷移可能

**権限による表示制御**：
- SQL Server接続権限が必要
- sys.dm_os_waiting_tasks への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 415 | Get-DbaWaitingTask | 主機能 | 待機中タスクの詳細情報取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaWaitingTask`

## 入出力項目

### Get-DbaWaitingTask パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstance[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Spid | object[] | No | フィルタ対象のセッションID |
| IncludeSystemSpid | switch | No | システムセッションを含める |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

### Get-DbaWaitingTask 出力プロパティ

| プロパティ名 | 型 | 説明 | デフォルト表示 |
|-------------|------|------|---------------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 | Yes |
| InstanceName | string | SQL Serverインスタンス名 | Yes |
| SqlInstance | string | 完全なSQL Serverインスタンス名 | Yes |
| Spid | int | 待機中セッションのセッションID | Yes |
| Thread | int | 実行コンテキストID（スレッド番号） | Yes |
| Scheduler | int | スケジューラID | Yes |
| WaitMs | long | 待機時間（ミリ秒） | Yes |
| WaitType | string | 待機タイプ（CXPACKET、LCK_M_IX等） | Yes |
| BlockingSpid | int | ブロッキングセッションID（0はブロッキングなし） | Yes |
| ResourceDesc | string | リソース記述（ページID等） | No |
| NodeId | string | CXPACKET待機のパラレル交換ノードID | No |
| Dop | int | 並列実行の並列度 | No |
| DbId | int | 待機発生データベースID | No |
| SqlText | string | 実行中のSQLテキスト | No |
| QueryPlan | xml | クエリ実行プラン | No |
| InfoUrl | xml | SQLSkills待機タイプドキュメントURL | No |

## イベント仕様

### 1-Get-DbaWaitingTask実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続（最小バージョン: SQL Server 2005）
2. IncludeSystemSpidフラグに基づきWHERE句を構築
3. 複数DMVを結合するクエリを実行：
   - sys.dm_os_waiting_tasks
   - sys.dm_os_tasks
   - sys.dm_exec_sessions
   - sys.dm_exec_requests
   - sys.dm_exec_query_memory_grants
   - sys.dm_exec_sql_text
   - sys.dm_exec_query_plan
4. CXPACKET待機の場合はNodeIdを抽出
5. Spidパラメータでフィルタリング
6. Select-DefaultViewで非表示プロパティを設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaWaitingTask | sys.dm_os_waiting_tasks | SELECT | 待機タスク取得 |
| Get-DbaWaitingTask | sys.dm_os_tasks | SELECT | タスク情報取得 |
| Get-DbaWaitingTask | sys.dm_exec_sessions | SELECT | セッション情報取得 |
| Get-DbaWaitingTask | sys.dm_exec_requests | SELECT | リクエスト情報取得 |
| Get-DbaWaitingTask | sys.dm_exec_query_memory_grants | SELECT | メモリグラント情報取得 |
| Get-DbaWaitingTask | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |
| Get-DbaWaitingTask | sys.dm_exec_query_plan | SELECT | クエリプラン取得 |

### テーブル別更新項目詳細

本機能は読み取り専用のため、データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Error | 接続失敗 | "Failure" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |
| SQL Server 2005未満 | MinimumVersion 9 により自動的にスキップ |

## 備考

- IncludeSystemSpidを指定しない場合、is_user_process = 1でフィルタ
- CXPACKETやCXCONSUMER待機の場合、ResourceDescからNodeIdを抽出
- InfoUrlは https://www.sqlskills.com/help/waits/{WaitType} 形式
- OPTION(RECOMPILE)でクエリプランのキャッシュを回避
- 参考資料:
  - https://www.sqlskills.com/blogs/paul/updated-sys-dm_os_waiting_tasks-script-2/

---

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

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

### 推奨読解順序

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

待機タスク情報のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | 146-163行目: 出力PSCustomObjectの構造定義 |

**読解のコツ**: Select-DefaultViewの-ExcludePropertyでどのプロパティがデフォルト非表示か確認。

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

処理の起点となるコマンドレット関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | 82-91行目: param()ブロックでパラメータ定義を確認 |

**主要処理フロー**:
1. **133-138行目**: Connect-DbaInstanceでSQL Server接続
2. **140行目**: Server.Query()でSQLクエリ実行
3. **141-144行目**: Spidフィルタリング
4. **146-163行目**: 結果オブジェクト構築

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | 94-130行目: 待機タスク取得クエリ全体 |

**主要処理フロー**:
- **96-112行目**: SELECT句（カラム選択とCXPACKET NodeId抽出）
- **103-108行目**: CXPACKET待機時のNodeId抽出（CASE式）
- **113行目**: InfoUrl生成（SQLSkillsへのリンク）
- **114-124行目**: FROM句とJOIN（複数DMVの結合）
- **125-126行目**: WHERE句（IncludeSystemSpid対応）
- **127-130行目**: ORDER BY と OPTION(RECOMPILE)

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

```
Get-DbaWaitingTask
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |       +-- SMO Server Object生成
    |
    +-- Server.Query()
    |       +-- sys.dm_os_waiting_tasks (メイン)
    |       +-- INNER JOIN sys.dm_os_tasks
    |       +-- INNER JOIN sys.dm_exec_sessions
    |       +-- INNER JOIN sys.dm_exec_requests
    |       +-- FULL JOIN sys.dm_exec_query_memory_grants
    |       +-- OUTER APPLY sys.dm_exec_sql_text
    |       +-- OUTER APPLY sys.dm_exec_query_plan
    |
    +-- Spid Filter (PowerShell側)
    |
    +-- Select-DefaultView
            +-- ExcludeProperty: SqlText, QueryPlan, InfoUrl
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance  ----+
                                                 |
SqlCredential  ------>                           |
                                                 |
IncludeSystemSpid -->  WHERE句構築              |
                             |                   |
                             v                   v
                        Server.Query()       --> DMV Query
                             |
                             +-- dm_os_waiting_tasks
                             +-- dm_os_tasks
                             +-- dm_exec_sessions
                             +-- dm_exec_requests
                             +-- dm_exec_query_memory_grants
                             +-- dm_exec_sql_text
                             +-- dm_exec_query_plan
                             |
                             v
Spid Filter    ------>  PowerShell Filter
                             |
                             v
                        PSCustomObject
                             |
                             v
                        Select-DefaultView (ExcludeProperty)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | ソース | 待機タスク取得の主処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
