# 機能設計書 392-Get-DbaPfDataCollectorCounterSample

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaPfDataCollectorCounterSample` 関数の機能設計を記述する。この関数は、SQL Serverシステムからリアルタイムのパフォーマンスカウンターサンプルを取得するための機能を提供する。

### 本機能の処理概要

`Get-DbaPfDataCollectorCounterSample` は、Windows Performance Monitorのカウンターからリアルタイムのパフォーマンスデータを収集する機能である。PowerShellの`Get-Counter`コマンドレットをラップし、CPU、メモリ、ディスクI/O、SQL Server固有のメトリクスなど、DBAがモニタリングに使用する構造化されたパフォーマンスデータを提供する。

**業務上の目的・背景**：SQL Serverの運用において、リアルタイムのパフォーマンスモニタリングは問題の早期検出と迅速なトラブルシューティングに不可欠である。本機能により、DBAは単一のスナップショットによるクイックチェックから、トラブルシューティングセッション中の継続的なモニタリングまで、柔軟なパフォーマンスデータ収集が可能となる。

**機能の利用シーン**：
- SQL Serverパフォーマンス問題のリアルタイムトラブルシューティング
- クエリ実行中のパフォーマンスメトリクス監視
- ベースラインデータ収集のための複数サンプル取得
- システム負荷イベント中のパフォーマンストレンド監視

**主要な処理内容**：
1. Get-DbaPfDataCollectorCounterからカウンター情報を取得
2. Get-Counterコマンドレットを使用してパフォーマンスサンプルを収集
3. 収集したサンプルデータを構造化されたオブジェクトに変換
4. 継続モード（-Continuous）または固定回数のサンプリングを実行

**関連システム・外部連携**：Windows Performance Monitor APIと連携し、Get-Counterコマンドレットを介してパフォーマンスデータを収集する。

**権限による制御**：ローカルコンピューターでの実行には管理者権限が推奨。リモートコンピューターへのアクセスにはWMI/CIM権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |
| N/A | Windows Performance Monitor | 参照画面 | カウンター構成確認 |

## 機能種別

データ取得処理 (Read-Only) / リアルタイムモニタリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | パフォーマンスカウンターを収集するコンピューター名 | デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報 | Get-Credentialで生成 |
| CollectorSet | string[] | No | サンプリング対象のData Collector Set名 | エイリアス: DataCollectorSet |
| Collector | string[] | No | サンプリング対象のData Collector名 | エイリアス: DataCollector |
| Counter | string[] | No | 個別のカウンターパス | Windows Performance Monitor形式 |
| Continuous | switch | No | 継続サンプリングモード（CTRL+Cで停止） | - |
| ListSet | switch[] | No | 利用可能なカウンターセットを一覧表示 | - |
| MaxSamples | int | No | 最大サンプル数 | デフォルト: 1 |
| SampleInterval | int | No | サンプル間隔（秒） | 最小値: 1 |
| InputObject | object[] | No | Get-DbaPfDataCollectorCounterからのパイプライン入力 | ValueFromPipeline |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Windows Performance Counterシステム（Get-Counter経由）
- Get-DbaPfDataCollectorCounter関数からのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| DataCollectorSet | string | Data Collector Set名 |
| DataCollector | string | Data Collector名 |
| Name | string | カウンター名/パス |
| Timestamp | DateTime | カウンター収集タイムスタンプ |
| Path | string | カウンターパス（Performance Monitor形式） |
| InstanceName | string | カウンターサンプルのインスタンス名 |
| CookedValue | double | 処理済み/計算済みカウンター値 |
| RawValue | long | 処理前の生カウンター値 |
| SecondValue | long | 特定カウンタータイプの二次値 |
| MultipleCount | int | サンプルの複数カウント値 |
| CounterType | PerformanceCounterType | パフォーマンスカウンタータイプ |
| SampleTimestamp | datetime | 個別サンプルのタイムスタンプ |
| SampleTimestamp100NSec | long | 100ナノ秒単位のタイムスタンプ |
| Status | PerformanceCounterSampleStatus | サンプルステータス |
| DefaultScale | int | カウンターのデフォルトスケール係数 |
| TimeBase | long | カウンターのタイムベース値 |

### 出力先

PowerShellパイプライン（PSCustomObjectまたはGet-Counter生出力）

## 処理フロー

### 処理シーケンス

```
1. パラメーター検証とCredential/Counter継承
   └─ InputObjectからCredentialまたはCounterを継承

2. InputObjectの取得または生成
   └─ パイプライン入力がない場合: Get-DbaPfDataCollectorCounterを呼び出し

3. InputObject型の検証
   └─ CounterObjectプロパティの存在確認

4. カウンターごとにサンプル収集
   ├─ Get-Counterパラメーター構築
   ├─ Continuousモード: Get-Counter直接出力
   └─ 非Continuousモード: サンプルデータをPSCustomObjectに変換
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObjectに<br>Credentialあり?}
    B -->|Yes| C[Credential継承]
    B -->|No| D{InputObject.Counter<br>あり?}
    C --> D
    D -->|Yes| E[Counter継承]
    D -->|No| F{InputObject指定?}
    E --> F
    F -->|No| G[Get-DbaPfDataCollectorCounter呼び出し]
    F -->|Yes| H{型チェック}
    G --> H
    H -->|不正| I[Stop-Function]
    H -->|正常| J[カウンターイテレーション]
    J --> K[Get-Counterパラメーター構築]
    K --> L{Continuous?}
    L -->|Yes| M[Get-Counter直接出力]
    L -->|No| N[Get-Counter実行]
    N --> O[サンプルデータ変換]
    O --> P[PSCustomObject出力]
    P --> J
    M --> Q[終了]
    J -->|完了| Q
    I --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Credential継承 | InputObjectにCredentialがある場合は継承 | InputObject.Credential存在かつCredential未指定 |
| BR-002 | Counter継承 | InputObjectにCounterがある場合は継承 | InputObject.Counter存在かつCounter未指定 |
| BR-003 | Continuousモード出力 | Continuous指定時はGet-Counterの生出力を返す | -Continuous指定時 |
| BR-004 | ローカルホスト判定 | ローカルホストの場合はComputerNameを渡さない | IsLocalHost判定 |

### 計算ロジック

- CookedValue: パフォーマンスカウンターの計算済み値（Get-Counterが計算）
- RawValue: 生のカウンター値

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

本機能はデータベース操作を行わない。Windows Performance Counterシステムからリアルタイムデータを取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | InputObjectがGet-DbaPfDataCollectorCounterからの出力でない | Stop-Functionで処理中断 |
| - | カウンターエラー | 指定カウンターが存在しないまたはアクセス不可 | Stop-Function -Continueで次へ |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし（読み取り専用）

## パフォーマンス要件

- MaxSamplesとSampleIntervalによりデータ収集量を制御
- 高頻度サンプリング時はシステムリソースへの影響を考慮

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

- リモートアクセスには適切な資格情報が必要
- パフォーマンスカウンターへのアクセス権限が必要

## 備考

- `-Continuous`モードはCTRL+Cで停止するまで継続
- 60サンプルを1秒間隔で収集すれば1分間のベースラインデータが取得可能
- `Get-DbaPfDataCollectorCounter`とシームレスに連携

---

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

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

### 推奨読解順序

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

サンプルデータを保持するPSCustomObjectの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPfDataCollectorCounterSample.ps1 | `public/Get-DbaPfDataCollectorCounterSample.ps1` | 209-229行目のPSCustomObject構造を確認 |

**読解のコツ**: Get-CounterコマンドレットのCounterSamplesプロパティから取得したデータを構造化している。CookedValue（計算済み値）とRawValue（生値）の違いに注目。

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

関数のパラメーター定義と入力検証を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollectorCounterSample.ps1 | `public/Get-DbaPfDataCollectorCounterSample.ps1` | 127-143行目のパラメーター定義 |

**主要処理フロー**:
1. **136行目**: Continuousスイッチで継続モードを制御
2. **138行目**: MaxSamplesで収集回数を制限
3. **139行目**: SampleIntervalでサンプリング間隔を設定

#### Step 3: カウンターサンプリング処理を理解する

Get-Counterを使用したサンプリングロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollectorCounterSample.ps1 | `public/Get-DbaPfDataCollectorCounterSample.ps1` | 168-232行目のサンプリング処理 |

**主要処理フロー**:
- **170-196行目**: Get-Counterパラメーター構築（ハッシュテーブル使用）
- **198-199行目**: Continuousモード時の直接出力
- **201-205行目**: 非Continuousモード時のGet-Counter実行
- **207-231行目**: サンプルデータの構造化と出力

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

```
Get-DbaPfDataCollectorCounterSample
    │
    ├─ Get-DbaPfDataCollectorCounter (InputObject未指定時)
    │      └─ Get-DbaPfDataCollector
    │             └─ Get-DbaPfDataCollectorSet
    │
    ├─ Get-Counter (PowerShell標準コマンドレット)
    │      └─ Windows Performance Counter API
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

ComputerName ─────▶ Get-DbaPfDataCollectorCounter ─▶ PSCustomObject
CollectorSet              │                           - Timestamp
Collector                 │                           - CookedValue
Counter                   ▼                           - RawValue
MaxSamples ──────▶ Get-Counter ────────────────────▶ - Path
SampleInterval            │                           - InstanceName
InputObject ─────────────┘                            - CounterType
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollectorCounterSample.ps1 | `public/Get-DbaPfDataCollectorCounterSample.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | ソース | カウンター情報取得 |
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | Data Collector情報取得 |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | Data Collector Set情報取得 |
