# 機能設計書 415-Get-DbaWaitingTask

## 概要

本ドキュメントは、現在待機中のセッションとその待機タイプに関する詳細情報をSQL Server動的管理ビューから取得する`Get-DbaWaitingTask`機能の設計を定義する。

### 本機能の処理概要

本機能は、sys.dm_os_waiting_tasksおよび関連DMVをクエリして、現在待機中のセッションを特定し、待機タイプ、待機時間、ブロッキングセッション、SQLテキスト、クエリプランを含む包括的な診断情報を取得する。

**業務上の目的・背景**：DBAがパフォーマンスボトルネックを迅速に特定し、ブロッキング問題をトラブルシューティングし、リアルタイムで何が遅延を引き起こしているかを分析するのを支援する。出力にはCXPACKET待機の並列度、リソース記述、詳細分析のためのSQLSkills待機タイプドキュメントへの直接リンクなどの有用なコンテキストが含まれる。

**機能の利用シーン**：
- リアルタイムブロッキング問題の調査
- 並列クエリの問題診断（CXPACKET待機）
- 現在実行中のクエリの待機状態確認
- パフォーマンスモニタリング

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続（最小バージョン2005）
2. sys.dm_os_waiting_tasks、sys.dm_os_tasks、sys.dm_exec_sessions等を結合
3. 各待機タスクの詳細情報を構造化オブジェクトとして出力
4. オプションでシステムSPIDを含める、特定SPIDでフィルタ

**関連システム・外部連携**：
- 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

**権限による制御**：VIEW SERVER STATE権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

データ取得・リアルタイムモニタリング処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス（2005以降） | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| Spid | object[] | No | 特定のセッションIDでフィルタ | ValueFromPipelineByPropertyName |
| IncludeSystemSpid | switch | No | システムセッションを含める | - |
| EnableException | switch | No | 例外の詳細表示有効化 | - |

### 入力データソース

SQL Server DMV: sys.dm_os_waiting_tasks、sys.dm_os_tasks、sys.dm_exec_sessions、sys.dm_exec_requests等

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 | デフォルト表示 |
|--------|-----|------|---------------|
| 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 | int | 待機時間（ミリ秒） | 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 | string | SQLSkills待機タイプドキュメントURL | No |

### 出力先

PowerShellパイプライン(PSCustomObject)

## 処理フロー

### 処理シーケンス

```
1. beginブロック: SQLクエリ定義
   └─ 複数DMVを結合する詳細クエリを構築
   └─ IncludeSystemSpidに応じてis_user_processフィルタを動的設定

2. processブロック: インスタンスごとの処理ループ
   └─ 2.1 Connect-DbaInstance（MinimumVersion 9）で接続
   └─ 2.2 SQLクエリ実行
   └─ 2.3 Spidパラメータ指定時はフィルタ
   └─ 2.4 各行をPSCustomObjectに変換
   └─ 2.5 Select-DefaultViewで出力（SqlText, QueryPlan, InfoUrl除外）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ定義]
    B --> C{IncludeSystemSpid?}
    C -->|Yes| D[is_user_process=0]
    C -->|No| E[is_user_process=1]
    D --> F{各SqlInstanceをループ}
    E --> F
    F --> G[Connect-DbaInstance MinVer=9]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function/Continue]
    I --> F
    H -->|Yes| J[クエリ実行]
    J --> K{各行をループ}
    K --> L{Spid指定あり?}
    L -->|Yes| M{行のSpid in Spid?}
    M -->|No| N[continue]
    M -->|Yes| O[PSCustomObject作成]
    L -->|No| O
    O --> P[Select-DefaultView出力]
    P --> K
    K -->|完了| F
    F -->|完了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005（バージョン9）以上が必要 | Connect-DbaInstance時 |
| BR-002 | ユーザープロセス限定 | デフォルトはユーザープロセス（is_user_process=1）のみ | IncludeSystemSpid未指定時 |
| BR-003 | CXPACKET NodeId抽出 | CXPACKETの場合、resource_descriptionからnodeidを抽出 | WaitType=CXPACKET時 |
| BR-004 | RECOMPILEヒント | クエリにOPTION(RECOMPILE)を付与して最新プラン使用 | 常時 |

### 計算ロジック

```sql
-- CXPACKET NodeId抽出
CASE [owt].[wait_type]
    WHEN N'CXPACKET' THEN
        RIGHT ([owt].[resource_description],
            CHARINDEX (N'=', REVERSE ([owt].[resource_description])) - 1)
    ELSE NULL
END AS [NodeId]
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 待機タスク取得 | sys.dm_os_waiting_tasks | SELECT | 待機中タスク情報 |
| タスク情報取得 | sys.dm_os_tasks | SELECT | タスクとスケジューラ情報 |
| セッション情報取得 | sys.dm_exec_sessions | SELECT | セッション情報 |
| リクエスト情報取得 | sys.dm_exec_requests | SELECT | 実行中リクエスト |
| メモリ付与情報取得 | sys.dm_exec_query_memory_grants | SELECT | メモリ付与とDOP |
| SQLテキスト取得 | sys.dm_exec_sql_text | CROSS APPLY | 実行中SQL |
| クエリプラン取得 | sys.dm_exec_query_plan | OUTER APPLY | 実行プラン |

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

#### sys.dm_os_waiting_tasks (DMV)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | session_id, exec_context_id | - | SPID, Thread |
| SELECT | wait_duration_ms | - | 待機時間 |
| SELECT | wait_type | - | 待機タイプ |
| SELECT | blocking_session_id | - | ブロッキングSPID |
| SELECT | resource_description | - | リソース記述 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | Connect-DbaInstance失敗 | Stop-FunctionでContinue |
| VersionError | バージョンエラー | SQL Server 2005未満 | MinimumVersionで接続拒否 |

### リトライ仕様

リトライ処理なし（単一試行）

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

読み取り専用クエリのためトランザクション管理不要

## パフォーマンス要件

- DMVクエリのため通常は高速（数秒以内）
- dm_exec_sql_text/dm_exec_query_planのOUTER APPLYによる追加コスト
- OPTION(RECOMPILE)でプランキャッシュ影響を回避

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

- VIEW SERVER STATE権限が必要
- SQL認証/Windows認証/Azure AD認証に対応
- 資格情報はPSCredentialで安全に渡される

## 備考

- Paul Randal氏の参照記事: https://www.sqlskills.com/blogs/paul/updated-sys-dm_os_waiting_tasks-script-2/
- Shawn Melton氏(@wsmelton)による開発

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: 複数DMVから取得したデータを単一オブジェクトに統合している

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | パラメータ定義（83-91行目） |

**主要処理フロー**:
1. **83-91行目**: パラメータ定義（SqlInstance, Spid, IncludeSystemSpid）
2. **87-88行目**: SpidパラメータはValueFromPipelineByPropertyName対応

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | beginブロックのSQL定義（93-131行目） |

**主要処理フロー**:
- **94-130行目**: 複数DMVを結合する詳細クエリ
- **104-108行目**: CXPACKET NodeId抽出ロジック
- **114-124行目**: 5つのDMVをJOIN/APPLY
- **126行目**: is_user_processによる動的フィルタ（Test-Bound使用）
- **130行目**: OPTION(RECOMPILE)

#### Step 4: 結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | processブロックの処理（132-166行目） |

**主要処理フロー**:
- **140行目**: $server.Query($sql)でクエリ実行
- **141-144行目**: Spidパラメータによるフィルタ
- **146-162行目**: PSCustomObject作成
- **163行目**: Select-DefaultViewでSqlText/QueryPlan/InfoUrl除外

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

```
Get-DbaWaitingTask
    │
    ├─ beginブロック
    │      └─ SQLクエリ構築（5つのDMV結合）
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │      └─ SMO接続の確立
    │
    ├─ $server.Query()
    │      └─ 待機タスククエリ実行
    │
    └─ Select-DefaultView
           └─ 出力プロパティの選択
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──────┐
                   (MinimumVersion=9)         │
                                              │
SqlCredential ────▶ 認証処理 ────────────────┘
                          │
IncludeSystemSpid ▶ is_user_process設定
                          │
                          ▼
              ┌───────────────────────────────────────┐
              │ 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_...   │
              │    OUTER APPLY sys.dm_exec_sql_text   │
              │    OUTER APPLY sys.dm_exec_query_plan │
              └───────────────────────────────────────┘
                          │
                          ▼
                   foreach ($row in results)
                          │
Spid ─────────────▶ フィルタ処理
                          │
                          ▼
                   PSCustomObject
                          │
                          ▼
               Select-DefaultView
                          │
                          ▼
                   パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWaitingTask.ps1 | `public/Get-DbaWaitingTask.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
