# 機能設計書 390-Get-DbaPfDataCollector

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるGet-DbaPfDataCollector機能の設計仕様を記載する。本機能は、ローカルまたはリモートコンピュータからWindows Performance Monitorのデータコレクターとその設定詳細を取得する。

### 本機能の処理概要

本機能は、コレクターセット内のWindows Performance Monitorデータコレクターに関する詳細情報を取得する。DBAsがSQL Serverパフォーマンスカウンターを監視するために一般的に使用され、既存のデータコレクターのXML設定を解析して、設定、ファイル場所、サンプル間隔、収集されている特定のパフォーマンスカウンターを表示する。

**業務上の目的・背景**：SQL Serverベースライン分析やトラブルシューティングのために、既存のパフォーマンスモニタリング設定を監査し、コレクター設定を確認し、どのパフォーマンスカウンターが取得されているかを特定する必要がある。本機能は複数コンピュータにわたって動作し、特定のコレクターセットのフィルタリングのためにGet-DbaPfDataCollectorSetと連携する。

**機能の利用シーン**：
- 既存パフォーマンスモニタリング設定の監査
- データコレクター設定の確認
- 収集されているカウンターの特定
- 複数サーバー間でのコレクター設定比較

**主要な処理内容**：
1. 対象のData Collector SetをGet-DbaPfDataCollectorSetで取得（または入力オブジェクトから）
2. Data Collector SetのXML設定を解析
3. PerformanceCounterDataCollector要素を抽出
4. 各コレクターの詳細情報をPSCustomObjectとして出力

**関連システム・外部連携**：Windows Performance Monitor（Data Collector Set XML設定）。

**権限による制御**：Data Collector Set設定の読み取り権限が必要。

## 関連画面

本機能はCLIベースのPowerShellコマンドレットであり、GUI画面との直接的な関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行とData Collector情報表示 |
| - | Windows Performance Monitor | 参照画面 | Data Collectorの確認 |

## 機能種別

データ取得（SELECT）/ 設定照会

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | 対象コンピュータ。デフォルトはローカル | - |
| Credential | PSCredential | No | リモートコンピュータ接続用資格情報 | - |
| CollectorSet | string[] | No | 対象コレクターセット名（エイリアス: DataCollectorSet） | ワイルドカード対応 |
| Collector | string[] | No | 対象データコレクター名（エイリアス: DataCollector） | ワイルドカード対応 |
| InputObject | object[] | No | Get-DbaPfDataCollectorSetからのパイプライン入力 | ValueFromPipeline |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力：InputObjectがValueFromPipelineをサポート
- Get-DbaPfDataCollectorSetからのData Collector Setオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | Data Collector Setがあるコンピュータ名 |
| DataCollectorSet | string | 親Data Collector Set名 |
| Name | string | Data Collector名 |
| DataCollectorType | string | コレクタータイプ（例: PerformanceCounterDataCollector） |
| DataSourceName | string | パフォーマンスカウンターデータソース名 |
| FileName | string | パフォーマンスデータが保存されるファイル名 |
| FileNameFormat | string | 出力ファイルの命名形式（例: monddyy） |
| FileNameFormatPattern | string | シーケンシャルファイル命名パターン |
| LatestOutputLocation | string | 最新コレクター出力の保存パス |
| LogAppend | bool | 既存ログファイルへの追記有無 |
| LogCircular | bool | サーキュラーバッファリング使用有無 |
| LogFileFormat | string | ログファイル形式（csv, binary, sql等） |
| LogOverwrite | bool | 既存ログデータの上書き有無 |
| SampleInterval | string | サンプリング間隔（ミリ秒） |
| SegmentMaxRecords | string | ログセグメントあたりの最大レコード数 |
| Counters | string[] | 収集されているパフォーマンスカウンターのコレクション |

### 追加プロパティ（非表示）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CounterDisplayNames | string[] | カウンターの表示名 |
| RemoteLatestOutputLocation | string | リモートアクセス用のUNCパス |
| DataCollectorSetXml | string | 親Data Collector SetのXML設定 |
| CollectorXml | object | このコレクターのXML設定 |
| DataCollectorObject | bool | データコレクターオブジェクトフラグ |
| Credential | PSCredential | リモートアクセス用認証情報 |

### 出力先

PowerShellパイプラインへPSCustomObjectとして出力（Select-DefaultViewで表示制御）。

## 処理フロー

### 処理シーケンス

```
1. 入力の処理
   └─ InputObjectのCredentialを継承（未指定時）
2. Data Collector Setの取得
   └─ InputObject未指定時: Get-DbaPfDataCollectorSetで取得
3. 入力検証
   └─ DataCollectorSetObjectプロパティの存在確認
4. 各Data Collector Setに対してループ
   └─ XML設定からPerformanceCounterDataCollectorを解析
5. 各コレクターに対してループ
   └─ Collectorフィルタリング適用
   └─ RemoteLatestOutputLocation計算
6. PSCustomObjectとして出力
   └─ Select-DefaultViewで表示プロパティ制御
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObjectにCredentialあり?}
    B -->|Yes| C[Credentialを継承]
    B -->|No| D{InputObject指定あり?}
    C --> D
    D -->|No| E[Get-DbaPfDataCollectorSetで取得]
    D -->|Yes| F{DataCollectorSetObject存在?}
    E --> F
    F -->|No| G[エラー: 不正な入力タイプ]
    F -->|Yes| H[各Data Collector Setでループ]
    H --> I[XMLからPerformanceCounterDataCollector解析]
    I --> J[各コレクターでループ]
    J --> K{Collectorフィルタに一致?}
    K -->|No| L{次のコレクターあり?}
    K -->|Yes| M[RemoteLatestOutputLocation計算]
    M --> N[PSCustomObject生成]
    N --> O[Select-DefaultViewで出力]
    O --> L
    L -->|Yes| J
    L -->|No| P{次のData Collector Setあり?}
    P -->|Yes| H
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | PerformanceCounterのみ | PerformanceCounterDataCollector要素のみを抽出 | 常時 |
| BR-002 | UNCパス変換 | LatestOutputLocationのドライブ文字を$に変換してUNCパス生成 | outputlocation存在時 |
| BR-003 | 表示プロパティ | $columnsで定義された16プロパティをデフォルト表示 | 常時 |
| BR-004 | Collectorフィルタ | -Collector指定時、名前が一致しないコレクターをスキップ | Collector指定時 |

### 計算ロジック

RemoteLatestOutputLocation計算:
```powershell
$dir = ($outputlocation).Replace(':', '$')
$remote = "\\$($set.ComputerName)\$dir"
```

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

本機能はデータベースを操作しない。

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | Windows Performance Monitor設定の照会のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力タイプエラー | DataCollectorSetObjectプロパティがない | Get-DbaPfDataCollectorSetからの入力を使用 |

### リトライ仕様

リトライ機能は実装されていない。

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

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

## パフォーマンス要件

- XML解析は軽量な操作
- 複数コンピュータは順次処理

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

- Data Collector Set設定の読み取り権限が必要
- Credentialパラメータでリモート認証可能
- 出力のCredentialプロパティはデフォルトで非表示

## 備考

- Get-DbaPfDataCollectorSetとパイプラインで連携
- Select-Object *で非表示プロパティも含めてすべて表示可能
- DataCollectorObject=trueはAdd-DbaPfDataCollectorCounterへのパイプライン用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | 出力オブジェクト構造（48-79行目の.OUTPUTS） |

**読解のコツ**: デフォルト表示プロパティは$columnsで定義。Select-Object *で追加プロパティにアクセス。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | パラメータ定義（102-113行目） |
| 2-2 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | beginブロック（114-116行目） |

**主要処理フロー**:
1. **102-113行目**: パラメータ定義。CollectorSetとCollectorのエイリアス
2. **115行目**: $columns変数でデフォルト表示プロパティを定義

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | 入力処理とData Collector Set取得（117-135行目） |
| 3-2 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | XML解析とオブジェクト生成（137-177行目） |

**主要処理フロー**:
- **120-122行目**: InputObjectのCredential継承
- **124-127行目**: Get-DbaPfDataCollectorSetでの取得
- **130-134行目**: 入力タイプ検証
- **138行目**: XMLからPerformanceCounterDataCollector抽出
- **140-142行目**: Collectorフィルタリング
- **144-150行目**: RemoteLatestOutputLocation計算
- **152-175行目**: PSCustomObject生成とSelect-DefaultView

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

```
Get-DbaPfDataCollector
    │
    ├─ Get-DbaPfDataCollectorSet
    │      └─ Data Collector Setオブジェクト取得
    │
    └─ Select-DefaultView
           └─ 表示プロパティ制御
```

### データフロー図

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

ComputerName ───┐
                │
CollectorSet ───┤
                │
Collector ──────┼──▶ Get-DbaPfDataCollector ──▶ PSCustomObject
                │    Set                        │
InputObject ────┘    ▼                          ├─ ComputerName
                     XML解析                    ├─ DataCollectorSet
                     (PerformanceCounter        ├─ Name
                      DataCollector)            ├─ Counters
                                                └─ その他設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | メイン機能実装 |
| Get-DbaPfDataCollector.Tests.ps1 | `tests/Get-DbaPfDataCollector.Tests.ps1` | テスト | 単体テスト |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | 依存 | Data Collector Set取得 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | 関連 | カウンター追加 |
