# 機能設計書 391-Get-DbaPfDataCollectorCounter

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaPfDataCollectorCounter` 関数の機能設計を記述する。この関数は、Windows Performance Monitor Data Collector Setsからパフォーマンスカウンター構成を取得するための機能を提供する。

### 本機能の処理概要

`Get-DbaPfDataCollectorCounter` は、Windows Performance Monitor Data Collector Sets内に構成されているパフォーマンスカウンターの一覧を取得する機能である。SQL Serverおよびシステムのパフォーマンス監視構成を監査し、どのメトリクスが収集されているかを確認するために使用される。

**業務上の目的・背景**：SQL Server運用において、パフォーマンスモニタリングはシステム健全性の維持とトラブルシューティングに不可欠である。本機能により、DBAは既存の監視設定を確認し、必要なパフォーマンスカウンターが正しく収集されているかを検証できる。環境を引き継いだ際の監視設定監査や、キャパシティプランニングのためのメトリクス確認に活用される。

**機能の利用シーン**：
- 既存のパフォーマンス監視構成の監査
- SQL Serverパフォーマンスカウンターの収集確認
- 新しい監視設定を追加する前の現状確認
- 複数サーバー間でのモニタリング構成比較

**主要な処理内容**：
1. 指定されたコンピューターに接続し、Data Collector Set情報を取得
2. `Get-DbaPfDataCollector` を使用してData Collector内のカウンター情報を抽出
3. カウンター名、出力ファイル名、関連するCollector Set情報を含むオブジェクトを生成
4. パイプラインに即座に出力

**関連システム・外部連携**：Windows Performance Monitor (PLA - Performance Logs and Alerts) サービスと連携し、COMオブジェクト (Pla.DataCollectorSet) を介してData Collector Set構成を取得する。

**権限による制御**：ローカルコンピューターでの実行には管理者権限が必要。リモートコンピューターへのアクセスには適切なWMI/CIM権限が必要であり、`-Credential` パラメーターで代替資格情報を指定可能。

## 関連画面

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

## 機能種別

データ取得処理 (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 | 特定のカウンターパス（例: '\Processor(_Total)\% Processor Time'） | Windows Performance Monitor形式 |
| InputObject | object[] | No | Get-DbaPfDataCollectorからのパイプライン入力 | ValueFromPipeline |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Windows Performance Monitor Data Collector Sets (COMオブジェクト経由)
- Get-DbaPfDataCollector関数からのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| DataCollectorSet | string | 親Data Collector Set名 |
| DataCollector | string | Data Collector名 |
| DataCollectorSetXml | string | Data Collector SetのXML構成（非表示） |
| Name | string | パフォーマンスカウンターのフルパス |
| FileName | string | 出力ファイル名 |
| CounterObject | bool | カウンターオブジェクトフラグ（非表示） |
| Credential | PSCredential | 使用された資格情報（非表示） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメーター検証とCredential継承
   └─ InputObjectにCredentialが含まれている場合は継承

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

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

4. カウンター情報のイテレーション
   ├─ 各Data Collectorのカウンター配列をループ
   ├─ Counterフィルターによる絞り込み
   └─ PSCustomObjectの生成と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObjectに<br>Credentialあり?}
    B -->|Yes| C[Credential継承]
    B -->|No| D{InputObject指定?}
    C --> D
    D -->|No| E[Get-DbaPfDataCollector呼び出し]
    D -->|Yes| F{型チェック}
    E --> F
    F -->|不正| G[Stop-Function]
    F -->|正常| H[カウンターイテレーション]
    H --> I{Counterフィルター<br>に一致?}
    I -->|No| H
    I -->|Yes| J[PSCustomObject生成]
    J --> K[パイプライン出力]
    K --> H
    H -->|完了| L[終了]
    G --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Credential継承 | InputObjectにCredentialが含まれる場合、パラメーター未指定時に継承する | InputObject.Credential存在かつCredential未指定 |
| BR-002 | カウンターフィルタリング | Counterパラメーター指定時、完全一致するカウンターのみ出力 | Counterパラメーター指定時 |
| BR-003 | デフォルト表示プロパティ | 一部のプロパティはSelect-DefaultViewで非表示 | 常時 |

### 計算ロジック

特になし（データ取得のみ）

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

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

本機能はデータベース操作を行わない。Windows Performance Monitor構成のみを読み取る。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | InputObjectがGet-DbaPfDataCollectorからの出力でない | Stop-Functionで処理中断、Get-DbaPfDataCollectorを使用するよう案内 |
| - | 接続エラー | リモートコンピューターへの接続失敗 | Credentialの確認、ネットワーク接続確認 |

### リトライ仕様

リトライ機能なし

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

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

## パフォーマンス要件

特定の要件なし。リモートコンピューターの応答時間に依存。

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

- リモートアクセスには適切な資格情報が必要
- Credentialオブジェクトは出力から除外されるが、オブジェクトに保持される
- 管理者権限が必要な操作

## 備考

- SQL Server固有のパフォーマンスカウンター（例: `\SQLServer:Buffer Manager\Page life expectancy`）の監視確認に有用
- `Get-DbaPfDataCollectorSet | Get-DbaPfDataCollector | Get-DbaPfDataCollectorCounter` のパイプラインチェーンで使用可能

---

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

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

### 推奨読解順序

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

パフォーマンスカウンター情報を保持するPSCustomObjectの構造を理解する。

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

**読解のコツ**: PowerShellのPSCustomObjectは動的にプロパティを持つオブジェクトを定義する。`Select-DefaultView -ExcludeProperty` で非表示プロパティを指定している点に注目。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | 93-104行目のパラメーター定義、109-127行目の入力処理 |

**主要処理フロー**:
1. **93-104行目**: CmdletBinding属性とパラメーター定義（DbaInstance型、PSCredential型）
2. **112-114行目**: InputObjectからのCredential継承ロジック
3. **116-120行目**: InputObject未指定時のGet-DbaPfDataCollector呼び出し

#### Step 3: 依存関数を理解する

Get-DbaPfDataCollectorがカウンター情報のソースとなる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | 137-178行目のData Collector解析ロジック |

**主要処理フロー**:
- **138行目**: XML解析でPerformanceCounterDataCollectorを取得
- **170行目**: Countersプロパティにカウンター配列を格納

#### Step 4: カウンター出力処理を理解する

カウンターのイテレーションと出力オブジェクト生成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | 129-143行目のカウンター出力ループ |

**主要処理フロー**:
- **129-130行目**: InputObjectのカウンター配列をイテレート
- **131行目**: Counterフィルターによる絞り込み
- **132-141行目**: PSCustomObject生成とパイプライン出力

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

```
Get-DbaPfDataCollectorCounter
    │
    ├─ Get-DbaPfDataCollector (InputObject未指定時)
    │      └─ Get-DbaPfDataCollectorSet
    │             └─ Invoke-Command2 (リモート実行)
    │                    └─ COM: Pla.DataCollectorSet
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

ComputerName ─────▶ Get-DbaPfDataCollector ─────▶ PSCustomObject
CollectorSet        (Data Collector取得)           - ComputerName
Collector                    │                     - DataCollectorSet
Counter                      │                     - DataCollector
InputObject ─────────────────┘                     - Name (カウンターパス)
                                                   - FileName
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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情報取得 |
