# 機能設計書 396-Invoke-DbaPfRelog

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Invoke-DbaPfRelog` 関数の機能設計を記述する。この関数は、Windowsのrelogコマンドのパイプライン互換ラッパーとして、パフォーマンスカウンターログを他のフォーマットに変換するための機能を提供する。

### 本機能の処理概要

`Invoke-DbaPfRelog` は、Windows Performance Monitorで収集したバイナリログファイル(.blg)を、CSV、TSV、SQL、またはバイナリ形式に変換するrelogコマンドのラッパー関数である。パフォーマンスカウンターをテキスト形式に抽出することで、分析ツールでの利用や長期保存が可能となる。

**業務上の目的・背景**：Performance Monitorで収集したバイナリログ(.blg)は直接分析しにくいため、CSV/TSVなどのテキスト形式やSQLデータベースへの変換が必要となる場合が多い。本機能により、DBAはパイプラインを使用して効率的にログファイルを変換し、Excelやパフォーマンス分析ツールで利用できる形式にできる。

**機能の利用シーン**：
- パフォーマンスログのテキスト形式（CSV/TSV）への変換
- 複数のログファイルの一括変換
- 特定の時間範囲のデータ抽出
- 特定のカウンターのみの抽出
- ODBCを使用したSQLデータベースへの直接出力

**主要な処理内容**：
1. 入力ファイルパス（.blg）の収集
2. relogコマンドパラメーターの構築
3. 出力ディレクトリの作成（必要な場合）
4. relogコマンドの実行
5. 変換されたファイルオブジェクトの返却

**関連システム・外部連携**：Windowsのrelogコマンド（cmd /c relog）を実行する。SQLタイプ出力時はODBC DSNを使用してSQLデータベースに接続する。

**権限による制御**：ローカルのPerfLogsフォルダーへのアクセスには管理者権限が必要な場合がある。リモートファイルへのアクセスには適切なネットワーク権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |
| N/A | ODBC Manager | 参照画面 | SQL出力用DSN構成 |

## 機能種別

ファイル変換処理 / 外部コマンド実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string[] | No | .blgファイルのパス | ValueFromPipelineByPropertyName、エイリアス: FullName |
| Destination | string | No | 出力ファイルパスまたはディレクトリ | - |
| Type | string | No | 出力形式（tsv/csv/bin/sql） | ValidateSet、デフォルト: tsv |
| Append | switch | No | 既存ファイルへの追記（binのみ） | -Type bin時のみ有効 |
| AllowClobber | switch | No | 既存ファイルの上書き許可 | - |
| PerformanceCounter | string[] | No | 抽出するカウンターパス | - |
| PerformanceCounterPath | string | No | カウンター一覧を含むテキストファイル | - |
| Interval | int | No | サンプリング間隔（n番目のデータポイントを使用） | - |
| BeginTime | datetime | No | データ抽出開始時刻 | - |
| EndTime | datetime | No | データ抽出終了時刻 | - |
| ConfigPath | string | No | relog設定ファイルパス | - |
| Summary | switch | No | ログファイルのサマリー表示（変換なし） | - |
| InputObject | object[] | No | Get-DbaPfDataCollector等からのパイプライン入力 | ValueFromPipeline |
| Multithread | switch | No | 並列処理の有効化 | - |
| AllTime | switch | No | すべてのログファイルを処理（最新のみでなく） | - |
| Raw | switch | No | relogコマンドの生出力を表示 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ローカルまたはリモートの.blgファイル
- Get-DbaPfDataCollector/Get-DbaPfDataCollectorSetからのパイプライン入力

## 出力仕様

### 出力データ（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | 変換されたファイルのフルパス |
| Name | string | ファイル名（拡張子付き） |
| Directory | DirectoryInfo | ファイルのディレクトリ |
| Extension | string | ファイル拡張子 |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | datetime | 作成日時 |
| LastWriteTime | datetime | 最終更新日時 |
| RelogFile | bool | NoteProperty（true固定） |

### 出力データ（-Raw指定時）

relogコマンドの生出力（文字列）を返す。

### 出力先

- PowerShellパイプライン（System.IO.FileInfo + RelogFile NoteProperty）
- -Raw指定時はString出力

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ -AppendはType binの場合のみ有効

2. パスの収集
   ├─ 直接指定のPathを追加
   └─ InputObjectからOutputLocation/LatestOutputLocationを取得

3. .blgファイルのフィルタリング
   └─ 重複除去

4. ファイルごとの処理
   ├─ 出力先の決定（Destination/元ファイルと同じ場所）
   ├─ relogパラメーター構築
   ├─ 出力ディレクトリ作成
   ├─ 既存ファイルのハンドリング（AllowClobber）
   └─ relog実行

5. 結果出力
   ├─ -Raw: 生出力を表示
   └─ 通常: FileInfoオブジェクトを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Append &<br>Type != bin?}
    B -->|Yes| C[Stop-Function]
    B -->|No| D[パスの収集]
    D --> E[InputObjectからパス抽出]
    E --> F[.blgフィルター & 重複除去]
    F --> G{ファイル<br>あり?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I[relogパラメーター構築]
    I --> J[出力ディレクトリ作成]
    J --> K{ファイル<br>存在?}
    K -->|Yes| L{AllowClobber?}
    K -->|No| M[relog実行]
    L -->|Yes| N[既存ファイル削除]
    L -->|No| O[Stop-Function -Continue]
    N --> M
    M --> P{Raw?}
    P -->|Yes| Q[生出力表示]
    P -->|No| R[成功チェック]
    R --> S[FileInfoオブジェクト生成]
    S --> T[RelogFile NoteProperty追加]
    T --> U[パイプライン出力]
    Q --> U
    O --> U
    U --> V{次ファイル?}
    V -->|Yes| I
    V -->|No| W[終了]
    C --> W
    H --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Append制限 | -Appendは-Type binの場合のみ使用可能 | Append指定時 |
| BR-002 | ファイル名生成 | パイプライン入力時はcomputername-collectorname-timestamp形式 | perfmonobjectフラグがtrue時 |
| BR-003 | DSN出力判定 | DestinationがDSNで始まる場合はSQL出力と判定 | Destination.StartsWith("DSN") |
| BR-004 | 既存ファイル保護 | AllowClobber未指定時は既存ファイルを上書きしない | AllowClobber未指定時 |
| BR-005 | 管理者権限チェック | C:\PerfLogsへのアクセス時は権限チェック | パスがC:\\.*Admin.*にマッチ時 |

### 計算ロジック

- 日時フォーマット: M/d/yyyy hh:mm:ss

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

### SQL出力時

-Type sqlかつDestinationにDSN指定時、ODBCを使用してSQLデータベースに直接出力する。形式: `DSN!counter_log`

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力エラー | AppendがType bin以外で指定 | Stop-Functionでエラー |
| - | ファイル未検出 | .blgファイルが見つからない | Stop-Functionで中断 |
| - | ファイル存在エラー | 出力先が存在しAllowClobber未指定 | Stop-Function -Continue |
| - | relog失敗 | relogコマンドの実行エラー | Stop-Function -Continue |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし。各ファイルは個別に処理される。

## パフォーマンス要件

- Multithreadオプションで並列処理可能
- 大量のファイル処理時はInvoke-Parallelを使用

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

- PerfLogsフォルダーへのアクセスには管理者権限が必要な場合がある
- SQL出力時のODBC DSNには適切な認証情報が必要

## 備考

- relogはWindowsの標準コマンドラインツール
- 入力がハングする場合は-Rawオプションで直接出力を確認
- Invoke-Parallelを使用した並列処理に対応

---

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

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

### 推奨読解順序

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

入力と出力のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | 434-437行目のFileInfo出力とRelogFile NotePropertyを確認 |

**読解のコツ**: 出力はSystem.IO.FileInfoオブジェクトにRelogFileというNotePropertyを追加したもの。Get-ChildItemの結果を拡張している。

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

パラメーター定義とbeginブロックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | 182-205行目のパラメーター定義、206-226行目のbeginブロック |

**主要処理フロー**:
1. **188-189行目**: ValidateSetでType（tsv/csv/bin/sql）を制限
2. **209-214行目**: BeginTime/EndTimeの文字列フォーマット
3. **220-225行目**: Destination設定状態の記録

#### Step 3: InputObject処理を理解する

パイプライン入力からの.blgファイルパス抽出を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | 233-276行目のInputObject処理 |

**主要処理フロー**:
- **236-237行目**: OutputLocationとRemoteOutputLocationの存在チェック（DataCollectorSet）
- **257-258行目**: LatestOutputLocationの存在チェック（DataCollector）
- **241-251, 261-271行目**: AllTimeフラグによるログファイル取得範囲の制御

#### Step 4: relog実行処理を理解する

relogコマンドの構築と実行を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | 288-449行目のscriptBlock定義と実行 |

**主要処理フロー**:
- **323-362行目**: relogパラメーター（$params）の構築
- **371-413行目**: 出力ファイル/ディレクトリの管理
- **418-444行目**: relog実行と結果処理

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

```
Invoke-DbaPfRelog
    │
    ├─ Test-ElevationRequirement (権限チェック)
    │
    ├─ Get-ChildItem (.blgファイル検索)
    │
    ├─ cmd /c relog (外部コマンド実行)
    │
    ├─ New-Item (ディレクトリ作成)
    │
    ├─ Remove-Item (既存ファイル削除)
    │
    └─ Invoke-Parallel (-Multithread時)
```

### データフロー図

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

Path (.blg) ─────────▶ パス収集 ─────────▶ System.IO.FileInfo
InputObject                    │               + RelogFile NoteProperty
    │                          ▼
    ├─ DataCollectorSet  relogパラメーター構築
    │    OutputLocation              │
    │                          ▼
    └─ DataCollector     cmd /c relog 実行
         LatestOutputLocation        │
                               ▼
                    ファイルオブジェクト返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | パイプライン入力元 |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | パイプライン入力元 |
