# 画面設計書 151-CPU使用率

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるCPU使用率監視機能の設計を定義する。SQL ServerインスタンスのCPU使用状況をリアルタイムおよび履歴ベースで取得・分析するための機能群を提供する。

### 本画面の処理概要

本機能は、SQL ServerのCPU使用状況を監視し、パフォーマンスのボトルネックを特定するための診断情報を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を調査する際、CPU使用率の把握は最も基本的かつ重要な診断指標である。本機能は、SQL Serverプロセス自体のCPU消費量だけでなく、他のプロセスやシステム全体のCPU状況も含めて包括的に監視できる。これにより、CPU高負荷の原因がSQL Server内部のクエリにあるのか、外部プロセスとの競合なのかを迅速に判断できる。

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

**主要な操作・処理内容**：
1. SQL ServerプロセスとWindowsスレッドの相関分析によるCPU消費クエリの特定
2. リングバッファからの履歴CPU使用率データの取得（最大256分）
3. SQL Server、他プロセス、システムアイドルのCPU使用率内訳表示
4. 特定の閾値以上のCPU使用スレッドのフィルタリング
5. パフォーマンストラブルシューティングのための詳細スレッド情報取得

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- `Get-DbaProcess`と連携してプロセス詳細情報を取得可能
- パイプラインで他のdbatools機能と連携可能

**権限による表示制御**：
- SQL Server接続権限が必要
- WMI/CIM経由でのWindowsパフォーマンスカウンター取得には管理者権限が推奨
- sys.dm_os_ring_buffers への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 405 | Get-DbaCpuUsage | 主機能 | SQL ServerプロセスとWindowsスレッドを相関させてCPU使用状況を取得 |
| 404 | Get-DbaCpuRingBuffer | 補助機能 | sys.dm_os_ring_buffersからCPU使用率履歴を取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

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

## 入出力項目

### Get-DbaCpuUsage パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Credential | PSCredential | No | Windows認証用資格情報（WMI接続用） |
| Threshold | int | No | CPU使用率フィルタ閾値（デフォルト: 0） |
| EnableException | switch | No | 例外処理の有効化 |

### Get-DbaCpuRingBuffer パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstance[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| CollectionMinutes | int | No | 取得する履歴の分数（デフォルト: 60） |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|------|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | スレッド識別子（ProcessName_ProcessID_ThreadID形式） |
| ContextSwitchesPersec | long | 1秒あたりのコンテキストスイッチ数 |
| ElapsedTime | long | スレッド作成からの経過時間（秒） |
| IDProcess | int | WindowsプロセスID |
| Spid | int | SQL ServerセッションID |
| PercentPrivilegedTime | double | 特権モードでの時間割合 |
| PercentProcessorTime | double | プロセッサ時間の使用率 |
| PercentUserTime | double | ユーザーモードでの時間割合 |
| PriorityBase | int | スレッドの基本優先度 |
| PriorityCurrent | int | スレッドの現在優先度 |
| StartAddress | long | スレッドコード開始アドレス |
| ThreadStateValue | string | スレッド状態の説明 |
| ThreadWaitReasonValue | string | 待機理由の説明 |
| Process | object | Get-DbaProcessからのプロセス情報 |
| Query | string | 最後に実行されたT-SQLクエリ |

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

| プロパティ名 | 型 | 説明 |
|-------------|------|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| RecordId | int | リングバッファのレコードID |
| EventTime | datetime | CPUサンプルの日時 |
| SQLProcessUtilization | int | SQL Serverプロセスの使用率（0-100） |
| SystemIdle | int | アイドル状態の割合（0-100） |
| OtherProcessUtilization | int | 他プロセスの使用率（100 - SystemIdle - SQLProcessUtilization） |

## イベント仕様

### 1-Get-DbaCpuUsage実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続
2. Get-DbaProcessで現在のSQL Serverプロセス一覧を取得
3. Get-DbaCmObjectでWin32_PerfFormattedData_PerfProc_Threadクラスを照会
4. SQL ServerのDMV（sys.dm_exec_sessions等）からSPIDとKPIDのマッピングを取得
5. WindowsスレッドIDとSQL Server SPIDを相関付け
6. Threshold以上のCPU使用率を持つスレッドをフィルタリング
7. 結果オブジェクトを構築して出力

### 2-Get-DbaCpuRingBuffer実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続（最小バージョン: SQL Server 2005）
2. sys.dm_os_sys_infoからcpu_ticksタイムスタンプを取得
3. sys.dm_os_ring_buffersからRING_BUFFER_SCHEDULER_MONITORレコードを照会
4. XMLデータをパースしてCPU使用率情報を抽出
5. CollectionMinutes分の履歴データをフィルタリング
6. 結果オブジェクトを構築して出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaCpuUsage | sys.dm_exec_sessions | SELECT | セッション情報取得 |
| Get-DbaCpuUsage | sys.dm_exec_requests | SELECT | リクエスト情報取得 |
| Get-DbaCpuUsage | sys.dm_os_workers | SELECT | ワーカー情報取得 |
| Get-DbaCpuUsage | sys.dm_os_threads | SELECT | スレッド情報取得 |
| Get-DbaCpuUsage | sysprocesses (SQL 2000) | SELECT | プロセス情報取得 |
| Get-DbaCpuRingBuffer | sys.dm_os_ring_buffers | SELECT | リングバッファ取得 |
| Get-DbaCpuRingBuffer | sys.dm_os_sys_info | SELECT | システム情報取得 |

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

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

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Error | 接続失敗 | "Failure" |
| - | Verbose | タイムスタンプ使用時 | "Using current timestamp of {timestamp}" |
| - | Verbose | SQL実行時 | "Executing Sql Statement: {sql}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |
| WMI接続失敗 | エラーログ出力後、該当インスタンスをスキップ |
| SQL Server 2005未満 | MinimumVersion 9 により自動的にスキップ |

## 備考

- Get-DbaCpuUsageはサーバー上のすべてのSQL Serverインスタンスの結果を返すが、Processカラムは指定した-SqlInstanceに固有
- リングバッファは通常256分までのデータを保持（システムの活動状況に依存）
- SQL Server 2000ではsysprocesses、SQL Server 2005以降ではDMVを使用
- 参考資料:
  - https://www.mssqltips.com/sqlservertip/2454/
  - https://www.sqlskills.com/blogs/glenn/sql-server-diagnostic-information-queries-detailed-day-16/

---

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

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

### 推奨読解順序

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

CPU使用率情報のデータ構造を理解する。出力はWin32_PerfFormattedData_PerfProc_ThreadクラスとSQL Server DMVの組み合わせ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaCpuUsage.ps1 | `public/Get-DbaCpuUsage.ps1` | 109-145行目: スレッド状態と待機理由の定義（$threadstates, $threadwaitreasons） |
| 1-2 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 144-153行目: 出力PSCustomObjectの構造定義 |

**読解のコツ**: PowerShellのPSCustomObjectは動的なオブジェクト構造。Add-Memberで追加されるプロパティに注目。

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

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

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

**主要処理フロー (Get-DbaCpuUsage)**:
1. **146-152行目**: Connect-DbaInstanceでSQL Server接続
2. **154行目**: Get-DbaProcessでプロセス情報取得
3. **155行目**: Get-DbaCmObjectでWMIスレッド情報取得
4. **157-165行目**: SQL ServerバージョンによりDMVクエリを分岐
5. **167-186行目**: スレッドとSPIDの相関付けと結果構築

#### Step 3: SQL Server接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SMO接続とSQL Server認証の処理 |

**主要処理フロー**:
- **149行目 (Get-DbaCpuUsage)**: Connect-DbaInstanceでサーバーオブジェクト取得
- **102行目 (Get-DbaCpuRingBuffer)**: MinimumVersion 9 でSQL Server 2005以降を要求

#### Step 4: WMI/CIMアクセスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | WMI/CIMクラスへのアクセス処理 |

**主要処理フロー**:
- **155行目**: Win32_PerfFormattedData_PerfProc_Threadクラスを照会

#### Step 5: リングバッファクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 114-140行目: CTEを使用したリングバッファXMLパース |

**主要処理フロー**:
- **107-111行目**: SQL ServerバージョンによるタイムスタンプSQL分岐
- **114-140行目**: RingBufferSchedulerMonitor CTEでXML解析
- **143-155行目**: 結果のイテレーションと出力

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

```
Get-DbaCpuUsage
    |
    +-- Connect-DbaInstance
    |       +-- SMO Server Object生成
    |
    +-- Get-DbaProcess
    |       +-- SQL Server DMV照会 (sys.dm_exec_*)
    |
    +-- Get-DbaCmObject
    |       +-- WMI Win32_PerfFormattedData_PerfProc_Thread
    |
    +-- Server.Query()
            +-- sys.dm_exec_sessions / sysprocesses

Get-DbaCpuRingBuffer
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |       +-- SMO Server Object生成
    |
    +-- Server.Query()
            +-- sys.dm_os_sys_info
            +-- sys.dm_os_ring_buffers (RING_BUFFER_SCHEDULER_MONITOR)
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance  ----+
                                                 |
SqlCredential  ------>                           |
                                                 v
Credential     ------>  Get-DbaCmObject     --> WMI Thread Data ----+
                             |                                       |
                             v                                       |
                        Win32_PerfFormattedData                      |
                             |                                       |
                             v                                       v
                        Get-DbaProcess      --> SQL Process Data --> 相関処理
                             |                                       |
                             v                                       |
                        DMV Query                                    |
                        (dm_exec_*/sysprocesses)                     |
                             |                                       |
                             v                                       v
                        SPID-KPID Mapping  --------------------> PSCustomObject
                                                                     |
                                                                     v
                                                              Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaCpuUsage.ps1 | `public/Get-DbaCpuUsage.ps1` | ソース | リアルタイムCPU使用率取得の主処理 |
| Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | ソース | 履歴CPU使用率取得の主処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | ソース | SQL Serverプロセス情報取得 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
