# 機能設計書 404-Get-DbaCpuRingBuffer

## 概要

本ドキュメントは、SQL Serverの内部リングバッファから履歴CPU使用率データを取得しパフォーマンス分析に活用する`Get-DbaCpuRingBuffer`機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンストラブルシューティングやキャパシティプランニングにおいて、CPU使用率の履歴データは重要な指標である。sys.dm_os_ring_buffersには、最大256分間の1分単位のCPU使用率データが内部的に保存されている。本機能は、Glen Berryの診断クエリに基づき、SQL Serverプロセス、他プロセス、システムアイドル時間の3つのメトリクスを抽出し、外部監視ツールなしでCPUトレンドを分析可能にする。

**機能の利用シーン**：
- 特定の期間中のCPUトレンドを分析する場合
- CPU急上昇とアプリケーションイベントの相関を調査する場合
- キャパシティプランニングのエビデンス収集時
- 高CPU使用率がSQL Serverか他のプロセスかを判定する場合

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続確立
2. 現在のCPUタイムスタンプの取得（バージョンにより異なるクエリ）
3. RING_BUFFER_SCHEDULER_MONITORからのXMLデータ解析
4. EventTimeの計算と指定期間のフィルタリング
5. CPU使用率メトリクス（SQL Server、他プロセス、アイドル）の出力

**関連システム・外部連携**：SQL Serverの動的管理ビュー`sys.dm_os_ring_buffers`および`sys.dm_os_sys_info`を参照する。外部システムとの連携はない。

**権限による制御**：VIEW SERVER STATE権限またはsysadminロールが必要。

## 関連画面

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

## 機能種別

データ取得（パフォーマンス監視）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象のSQL Serverインスタンス（カンマ区切りで複数指定可能） | DbaInstance型による検証 |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 | PowerShell資格情報オブジェクト |
| CollectionMinutes | int | No | 取得するCPU履歴の分数、デフォルト60分 | 整数値（最大約256分） |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- PowerShellコマンドライン入力
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾SQL Serverインスタンス名（computer\instance形式） |
| RecordId | int | リングバッファエントリの一意識別子 |
| EventTime | DateTime | CPUサンプルの日時（サーバーローカル時刻） |
| SQLProcessUtilization | int | SQL Serverプロセスによるcpu使用率（0-100%） |
| SystemIdle | int | システムアイドル時間の割合（0-100%） |
| OtherProcessUtilization | int | 他プロセスによるCPU使用率（0-100%）、100 - SystemIdle - SQLProcessUtilizationで計算 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance必須チェック

2. 各インスタンスに対してループ処理
   └─ Test-FunctionInterruptによる中断チェック
   └─ Connect-DbaInstanceによる接続確立（MinimumVersion 9）
   └─ 接続失敗時はStop-Functionで継続処理

3. 現在のタイムスタンプ取得
   └─ バージョン10以上: cpu_ticks / (cpu_ticks / ms_ticks)
   └─ バージョン9: cpu_ticks / cpu_ticks_in_ms

4. SQLクエリ実行
   └─ RING_BUFFER_SCHEDULER_MONITORからXMLデータ取得
   └─ EventTime計算とフィルタリング
   └─ CPU使用率の抽出

5. 結果オブジェクト出力
   └─ 各レコードをPSCustomObjectとしてパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceパラメータ取得]
    B --> C{Test-FunctionInterrupt?}
    C -->|Yes| Z[終了]
    C -->|No| D{各インスタンスでループ}
    D --> E[Connect-DbaInstance]
    E --> F{接続成功?}
    F -->|No| G[Stop-Function -Continue]
    G --> D
    F -->|Yes| H{バージョン > 9?}
    H -->|Yes| I[cpu_ticks/ms_ticks計算]
    H -->|No| J[cpu_ticks_in_ms計算]
    I --> K[リングバッファクエリ実行]
    J --> K
    K --> L{各レコードでループ}
    L --> M[PSCustomObject生成]
    M --> N[パイプライン出力]
    N --> L
    L -->|ループ終了| D
    D -->|ループ終了| Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2005以上が必要 | 接続時に検証 |
| BR-002 | デフォルト収集期間 | CollectionMinutesのデフォルトは60分 | 未指定時 |
| BR-003 | タイムスタンプ計算 | SQL Server 2008以降とSQL 2005でクエリが異なる | バージョンによる分岐 |
| BR-004 | CPU使用率計算 | OtherProcessUtilization = 100 - SystemIdle - SQLProcessUtilization | 常時適用 |

### 計算ロジック

- EventTime計算: `DATEADD(ss, (-1 * (currentTimestamp - timestamp))/1000, GETDATE())`
- 他プロセスCPU使用率: `100 - SystemIdle - SQLProcessUtilization`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| タイムスタンプ取得 | sys.dm_os_sys_info | SELECT | 現在のCPUタイムスタンプ取得 |
| CPU履歴取得 | sys.dm_os_ring_buffers | SELECT | リングバッファからCPUデータ抽出 |

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

#### sys.dm_os_ring_buffers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | record | XMLとして解析 | RING_BUFFER_SCHEDULER_MONITORのみ |
| SELECT | timestamp | EventTime計算に使用 | リングバッファタイムスタンプ |

#### XMLパース対象要素

| XPath | 取得内容 |
|-------|---------|
| (./Record/@id)[1] | record_id |
| (./Record/SchedulerMonitorEvent/SystemHealth/SystemIdle)[1] | SystemIdle |
| (./Record/SchedulerMonitorEvent/SystemHealth/ProcessUtilization)[1] | SQLProcessUtilization |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで処理継続 |
| - | VersionError | SQL Server 2005未満 | MinimumVersionで接続拒否 |

### リトライ仕様

自動リトライなし。

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

読み取り専用操作のため、トランザクション管理不要。

## パフォーマンス要件

- クエリ実行時間：通常1秒未満
- リングバッファ最大保持期間：約256分（システム活動に依存）

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

- VIEW SERVER STATE権限またはsysadminロールが必要
- SqlCredentialパラメータでSQL認証を使用可能
- MFA対応にはConnect-DbaInstanceの事前使用を推奨

## 備考

- Glen Berryの診断クエリに基づいた実装
- SQLSkillsのブログ記事を参照
- ConvertTo-DbaDataTableと組み合わせてData Tableへの変換が可能

---

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

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

### 推奨読解順序

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

PSCustomObjectとして返却されるオブジェクト構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 144-153行目の出力オブジェクト定義 |

**読解のコツ**: CPU使用率は3つのメトリクス（SQLProcessUtilization、OtherProcessUtilization、SystemIdle）に分解される。

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

処理の起点となる関数定義とパラメータを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 1-96行目のヘルプドキュメントとパラメータ定義 |

**主要処理フロー**:
1. **89-96行目**: パラメータ定義
2. **94行目**: CollectionMinutesのデフォルト値60を定義

#### Step 3: バージョン分岐処理を理解する

SQL Serverバージョンによるタイムスタンプ取得クエリの違い。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 107-111行目のバージョン分岐 |

**主要処理フロー**:
- **107-108行目**: バージョン10以上（SQL 2008+）のクエリ
- **109-110行目**: バージョン9（SQL 2005）のクエリ

#### Step 4: メインSQLクエリを理解する

リングバッファからCPUデータを抽出するSQLクエリ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | 114-140行目のSQLクエリ |

**主要処理フロー**:
- **114-131行目**: CTEによるリングバッファXML解析
- **132-140行目**: 結果選択とフィルタリング

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

```
Get-DbaCpuRingBuffer
    │
    ├─ Test-FunctionInterrupt (内部関数)
    │      └─ 処理中断チェック
    │
    ├─ Connect-DbaInstance (内部関数)
    │      └─ SQL Server接続確立
    │
    └─ $server.Query() (SMOメソッド)
           ├─ タイムスタンプ取得クエリ
           └─ リングバッファ取得クエリ
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ──────▶ $server
                                 │
SqlCredential ───────────────────┘
                                 │
                                 ▼
CollectionMinutes ─────▶ タイムスタンプ取得
                                 │
                                 ▼
                        リングバッファクエリ実行
                                 │
                                 ▼
                        XML解析・EventTime計算
                                 │
                                 ▼
                        PSCustomObject生成 ────────▶ パイプライン出力
                        (ComputerName, InstanceName,
                         SqlInstance, RecordId,
                         EventTime, SQLProcessUtilization,
                         OtherProcessUtilization, SystemIdle)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaCpuRingBuffer.ps1 | `public/Get-DbaCpuRingBuffer.ps1` | ソース | メイン機能実装 |
| Get-DbaCpuRingBuffer.Tests.ps1 | `tests/Get-DbaCpuRingBuffer.Tests.ps1` | テスト | Pesterユニットテスト |
