# 画面設計書 199-データコレクター

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWindowsパフォーマンスモニターData Collector取得機能の設計を記述する。Get-DbaPfDataCollector コマンドを中心に、Data Collectorセット内の個別のデータコレクターとその構成詳細を取得するための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：Data Collectorは、Data Collectorセット内でパフォーマンスカウンターの収集を定義する個々のコンポーネントである。どのカウンターを収集するか、サンプリング間隔、ファイル出力設定などを定義する。本機能により、既存のData Collector構成を監査し、収集対象のカウンターを確認し、監視設定のトラブルシューティングを行うことができる。SQL Serverのベースライン分析やパフォーマンストラブルシューティングの準備として有用である。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaPfDataCollector` コマンドを実行することでアクセスする。`Get-DbaPfDataCollectorSet` からパイプライン入力を受け取ることも可能。

**主要な操作・処理内容**：
1. Data CollectorセットのXML構成から個別のコレクター情報を抽出
2. PerformanceCounterDataCollector要素を解析
3. カウンター一覧、サンプリング間隔、ファイル設定などを取得
4. 出力パスをリモートアクセス用UNCパスに変換

**画面遷移**：本機能は `Get-DbaPfDataCollectorSet` の出力を入力として受け取る。取得したコレクターは `Get-DbaPfDataCollectorCounter` にパイプラインで渡すことができる。

**権限による表示制御**：Windowsのパフォーマンスモニター情報へのアクセス権限が必要。通常は管理者権限が必要である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 390 | Get-DbaPfDataCollector | 主機能 | データコレクターの取得 |
| 393 | Get-DbaPfDataCollectorSet | 補助機能 | データコレクターセットの取得（入力元） |
| 391 | Get-DbaPfDataCollectorCounter | 遷移先機能 | カウンターの取得 |

## 画面種別

一覧（コマンドライン出力）

## URL/ルーティング

PowerShellコマンド: `Get-DbaPfDataCollector`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstance[] | No | 対象コンピュータ（デフォルト: localhost） |
| Credential | PSCredential | No | 代替認証情報 |
| CollectorSet | string[] | No | 対象のコレクターセット名（エイリアス: DataCollectorSet） |
| Collector | string[] | No | 対象のコレクター名（エイリアス: DataCollector） |
| InputObject | object[] | No | パイプライン入力（Get-DbaPfDataCollectorSetからの入力） |
| EnableException | switch | No | 例外処理を有効化 |

### 出力プロパティ（デフォルト表示）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| DataCollectorSet | string | 親コレクターセット名 |
| Name | string | コレクター名 |
| DataCollectorType | string | コレクタータイプ |
| DataSourceName | string | データソース名 |
| FileName | string | 出力ファイル名 |
| FileNameFormat | string | ファイル名形式 |
| FileNameFormatPattern | string | ファイル名パターン |
| LatestOutputLocation | string | 最新出力パス |
| LogAppend | bool | ログ追記モード |
| LogCircular | bool | 循環ログモード |
| LogFileFormat | string | ログファイル形式 |
| LogOverwrite | bool | ログ上書きモード |
| SampleInterval | int | サンプリング間隔 |
| SegmentMaxRecords | int | セグメント最大レコード |
| Counters | string[] | カウンター一覧 |

### 出力プロパティ（追加プロパティ）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| CounterDisplayNames | string[] | カウンター表示名 |
| RemoteLatestOutputLocation | string | リモート出力パス（UNC） |
| DataCollectorSetXml | string | 親セットのXML構成 |
| CollectorXml | object | コレクターのXML要素 |
| DataCollectorObject | bool | オブジェクト識別フラグ |
| Credential | PSCredential | 認証情報 |

## 表示項目

デフォルトビューでは16プロパティが表示される。Select-Object * で全プロパティにアクセス可能。

## イベント仕様

### 1-データコレクター一覧取得

コマンド実行時に以下の処理フローが実行される:

1. **beginブロック**:
   - デフォルト表示プロパティのリストを定義

2. **processブロック**:
   - InputObjectからCredentialを取得（未指定時）
   - InputObjectがない場合は内部でGet-DbaPfDataCollectorSetを呼び出し
   - InputObjectの型チェック（DataCollectorSetObject必須）
   - 各Data CollectorセットのXMLからPerformanceCounterDataCollectorを抽出
   - Collector指定時は名前でフィルタリング
   - 各コレクターの情報をPSCustomObjectとして出力

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

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

本機能はWindowsパフォーマンスモニター構成の読み取りのみであり、データベースアクセスは行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Error | InputObject is not of the right type. Please use Get-DbaPfDataCollectorSet. | 不正な入力オブジェクト |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 型エラー | InputObjectがDataCollectorSetObjectでない場合 | Stop-Functionでエラー出力、処理中断 |

## 備考

- Data CollectorセットのXML構成から情報を抽出
- PerformanceCounterDataCollector型のコレクターのみを対象
- DataCollectorObjectプロパティでパイプライン連携時の型識別に使用
- Countersプロパティでそのコレクターが収集するカウンター一覧を取得可能
- Get-DbaPfDataCollectorCounterと組み合わせて詳細なカウンター情報を取得

---

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

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

### 推奨読解順序

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

Data Collectorオブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | .OUTPUTS セクションで出力オブジェクトの構造を確認（L48-79） |

**読解のコツ**: DataCollectorObjectプロパティは、他のdbatools関数がパイプライン入力を識別するために使用される。

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

Get-DbaPfDataCollector関数のパラメータとbeginブロックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | param()ブロックでパラメータ定義を確認（L102-113） |

**主要処理フロー**:
1. **L114-116**: beginブロックでデフォルト表示プロパティを定義
2. **L115**: 16個のデフォルト表示プロパティをリスト化

#### Step 3: メイン処理ロジックを理解する

コレクターの取得・フィルタリング・出力処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | processブロックのメイン処理（L117-178） |

**主要処理フロー**:
- **L120-122**: InputObjectからCredentialを取得
- **L124-128**: InputObjectがない場合はGet-DbaPfDataCollectorSetを呼び出し
- **L130-135**: InputObjectの型チェック
- **L137-138**: XMLからPerformanceCounterDataCollectorを抽出
- **L139-142**: Collector名でフィルタリング
- **L152-175**: PSCustomObjectを作成して出力

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

```
Get-DbaPfDataCollector
    |
    +-- デフォルト表示プロパティ定義 (beginブロック)
    |       └-- 16プロパティのリスト
    |
    +-- Credential取得
    |       └-- InputObject.Credentialまたはパラメータ
    |
    +-- Get-DbaPfDataCollectorSet (InputObjectがない場合)
    |       └-- Data Collectorセット取得
    |
    +-- 型チェック
    |       └-- DataCollectorSetObject必須
    |
    +-- foreach (InputObject)
    |       |
    |       +-- XML解析
    |       |       └-- PerformanceCounterDataCollector抽出
    |       |
    |       +-- Collectorフィルタリング
    |       |       └-- 名前マッチング
    |       |
    |       +-- UNCパス変換
    |       |       └-- LatestOutputLocation → リモートパス
    |       |
    |       └-- PSCustomObject作成
    |               └-- 全プロパティ設定
    |
    └-- Select-DefaultView
            └-- デフォルト表示設定
```

### データフロー図

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

ComputerName ────────┐
                     │
Credential ──────────┤    ┌─────────────────────┐
                     │    │ Get-DbaPfData       │
CollectorSet ────────┼───►│ CollectorSet        │
                     │    │ (内部呼び出し)       │
Collector ───────────┤    └──────────┬──────────┘
                     │               │
InputObject ─────────┘               ▼
                          ┌─────────────────────┐
                          │ XML解析             │
                          │ PerformanceCounter  │
                          │ DataCollector       │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ フィルタリング       │
                          │ - Collector名       │──►  PSCustomObject[]
                          │ - UNCパス変換       │     (コレクター一覧)
                          │ - プロパティ抽出    │
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | メイン関数定義 |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | 入力元：Data Collectorセット取得関数 |
| Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | ソース | 出力先：カウンター取得関数 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | ソース | カウンター追加関数 |
| Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | ソース | カウンター削除関数 |
