# 画面設計書 201-Relog

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるRelog機能（パフォーマンスログの変換・再フォーマット）の設計仕様を定義するものである。

### 本画面の処理概要

Relog機能は、Windowsパフォーマンスモニター（perfmon）で収集されたバイナリログファイル（.blg形式）を、分析しやすい形式（TSV、CSV、バイナリ、SQL）に変換する機能を提供する。SQL Serverのパフォーマンス分析において、perfmonデータを他のツールと連携させるために不可欠な機能である。

**業務上の目的・背景**：SQL Serverのパフォーマンストラブルシューティングでは、パフォーマンスカウンターのデータ収集が重要な役割を果たす。しかし、perfmonで収集された.blgファイルはバイナリ形式であり、直接Excelやテキストエディタで開くことができない。本機能は、これらのファイルをTSV/CSV形式に変換することで、Excelでのグラフ作成、PowerShellでのデータ分析、SQLデータベースへの直接インポートを可能にする。また、複数のサーバーから収集したパフォーマンスログを一括で変換・統合する運用ニーズに応える。

**画面へのアクセス方法**：PowerShellコンソールから`Invoke-DbaPfRelog`コマンドを実行する。パイプラインを通じて`Get-DbaPfDataCollector`や`Get-DbaPfDataCollectorSet`の出力を受け取ることも可能。

**主要な操作・処理内容**：
1. パフォーマンスログファイル（.blg）のパス指定と変換実行
2. 出力形式（TSV/CSV/バイナリ/SQL）の選択
3. 特定の時間範囲の抽出（BeginTime/EndTime指定）
4. 特定のパフォーマンスカウンターのみの抽出
5. サンプリング間隔の調整（Interval指定）
6. 複数ファイルのマルチスレッド並列処理
7. Data Collectorからのパイプライン入力による自動処理

**画面遷移**：
- 入力元：Get-DbaPfDataCollector、Get-DbaPfDataCollectorSetからのパイプライン入力
- 出力先：変換されたファイル（TSV/CSV/バイナリ）、またはSQLデータベース

**権限による表示制御**：管理者権限（Elevation）は、システム保護されたディレクトリ（C:\PerfLogs\Admin\など）へのアクセス時に必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 396 | Invoke-DbaPfRelog | 主機能 | パフォーマンスログのRelog実行 |
| - | Get-DbaPfDataCollector | 補助機能 | Data Collectorの取得とパイプライン入力 |
| - | Get-DbaPfDataCollectorSet | 補助機能 | Data Collector Setの取得とパイプライン入力 |

## 画面種別

コマンドラインインターフェース（CLI）/ バッチ処理

## URL/ルーティング

```powershell
# 基本的な使用法
Invoke-DbaPfRelog -Path <パス> [-Destination <出力先>] [-Type <形式>]

# パイプライン使用法
Get-DbaPfDataCollector | Invoke-DbaPfRelog
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| Path | string[] | 条件付き | - | 変換元の.blgファイルパス |
| Destination | string | No | 元ファイルと同じディレクトリ | 出力先パスまたはディレクトリ |
| Type | string | No | tsv | 出力形式（tsv/csv/bin/sql） |
| Append | switch | No | $false | 既存ファイルへの追記（binのみ） |
| AllowClobber | switch | No | $false | 既存ファイルの上書き許可 |
| PerformanceCounter | string[] | No | - | 抽出するパフォーマンスカウンター |
| PerformanceCounterPath | string | No | - | カウンターリストファイルのパス |
| Interval | int | No | - | サンプリング間隔（n番目ごと） |
| BeginTime | datetime | No | - | データ抽出開始時刻 |
| EndTime | datetime | No | - | データ抽出終了時刻 |
| ConfigPath | string | No | - | relog設定ファイルのパス |
| Summary | switch | No | $false | サマリー情報のみ表示 |
| InputObject | object[] | No | - | パイプライン入力オブジェクト |
| Multithread | switch | No | $false | 並列処理の有効化 |
| AllTime | switch | No | $false | 全ログファイルの処理 |
| Raw | switch | No | $false | relogコマンドの生出力を表示 |
| EnableException | switch | No | $false | 例外の有効化 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | 変換されたファイルの完全パス |
| Name | string | ファイル名（拡張子付き） |
| Directory | DirectoryInfo | ファイルが存在するディレクトリ |
| DirectoryName | string | ディレクトリの完全パス |
| Extension | string | ファイル拡張子 |
| Length | long | ファイルサイズ（バイト） |
| Attributes | FileAttributes | ファイル属性 |
| CreationTime | datetime | 作成日時 |
| LastAccessTime | datetime | 最終アクセス日時 |
| LastWriteTime | datetime | 最終更新日時 |
| RelogFile | bool | Relogで作成されたファイルを示すフラグ（常にtrue） |

## イベント仕様

### 1-変換実行イベント

ユーザーがInvoke-DbaPfRelogコマンドを実行すると、以下の処理フローが実行される：

1. パラメータ検証（BeginTime/EndTimeの文字列変換）
2. 入力パスの収集とフィルタリング（.blgファイルのみ）
3. 出力先ディレクトリの存在確認・作成
4. relogコマンドの実行（cmd /c経由）
5. 出力ファイルのFileInfoオブジェクト生成と返却

### 2-パイプライン入力イベント

Data CollectorまたはData Collector Setオブジェクトがパイプラインで渡された場合：

1. InputObjectからOutputLocation/RemoteOutputLocationを取得
2. AllTimeスイッチに基づき、最新ログまたは全ログを対象に
3. ローカル/リモートのパス判定と.blgファイルの検索
4. 通常の変換処理フローへ

### 3-マルチスレッド処理イベント

Multithreadスイッチが指定された場合：

1. 全入力パスをInvoke-Parallelに渡す
2. 各ファイルを並列で変換処理
3. エラーはVerboseメッセージとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| SQL出力時 | DSN指定のテーブル | INSERT | ODBCデータソース経由でパフォーマンスデータを挿入 |

### テーブル別更新項目詳細

#### SQL出力時のODBCテーブル

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | counter_log | perfmonカウンターデータ | DSN!counter_log形式で指定 |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| エラー | "Append can only be used with -Type bin." | Appendとbin以外のType指定時 |
| エラー | "Could not find matching .blg files" | 入力パスに.blgファイルがない場合 |
| エラー | "$file does not exist." | 指定ファイルが存在しない場合 |
| エラー | "$Destination exists. Use -AllowClobber to overwrite." | ファイルが既存でClobber指定なし |
| 警告 | relog実行時の標準エラー出力 | relog実行失敗時 |
| 成功 | "The command completed successfully." | 変換完了時（Raw指定時に表示） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ファイルが見つからない | Stop-Functionでメッセージ出力、処理継続 |
| 出力ディレクトリ作成失敗 | Stop-Functionでエラー記録、処理継続 |
| 管理者権限不足 | Test-ElevationRequirementでチェック、必要に応じてエラー |
| relog実行失敗 | Stop-Functionでメッセージ出力、処理継続 |

## 備考

- Windows環境専用の機能（relogコマンドがWindowsにのみ存在）
- SQL出力時は事前にODBC DSNの設定が必要
- 大容量ファイルの変換にはMultithreadオプションの使用を推奨

---

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

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

### 推奨読解順序

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

Invoke-DbaPfRelogはFileInfoオブジェクトにNotePropertyを追加して返却する。入力はパスの文字列またはData Collectorオブジェクトである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | 出力オブジェクトの構造（行437: RelogFile NoteProperty追加） |

**読解のコツ**: PowerShellのAdd-Member -MemberType NotePropertyで動的にプロパティを追加している点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | param()ブロックでパラメータ定義（行183-205） |

**主要処理フロー**:
1. **行206-226**: begin{}ブロックでBeginTime/EndTimeの文字列変換
2. **行227-276**: process{}ブロックでInputObjectからパスを収集
3. **行280-458**: end{}ブロックで実際の変換処理を実行

#### Step 3: パス収集ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | InputObjectからのパス抽出（行233-276） |

**主要処理フロー**:
- **行236-255**: DataCollectorSetオブジェクトの処理
- **行257-274**: DataCollectorオブジェクトの処理
- **行281**: .blgファイルのフィルタリングと重複排除

#### Step 4: 変換処理（ScriptBlock）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaPfRelog.ps1 | `public/Invoke-DbaPfRelog.ps1` | ScriptBlockによる変換処理（行288-449） |

**主要処理フロー**:
- **行294-299**: ファイル存在チェック
- **行301-303**: 管理者権限チェック（Admin配下のファイル用）
- **行305-321**: 出力先パスの決定
- **行323-362**: relogコマンドパラメータの構築
- **行371-413**: 出力ディレクトリの作成と既存ファイルの処理
- **行418-448**: relogコマンドの実行と結果処理

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

```
Invoke-DbaPfRelog
    |
    +-- begin{}
    |      +-- Test-Bound (BeginTime/EndTime検証)
    |
    +-- process{}
    |      +-- InputObject処理
    |             +-- Get-ChildItem (.blg検索)
    |             +-- [dbainstance] (ComputerName判定)
    |
    +-- end{}
           +-- ScriptBlock (変換処理)
           |      +-- Get-ChildItem (ファイル存在確認)
           |      +-- Test-ElevationRequirement (管理者権限チェック)
           |      +-- New-Item (ディレクトリ作成)
           |      +-- Remove-Item (既存ファイル削除)
           |      +-- cmd /c relog (変換実行)
           |      +-- Get-ChildItem (出力ファイル取得)
           |      +-- Add-Member (NoteProperty追加)
           |
           +-- Invoke-Parallel (マルチスレッド時)
                  +-- ScriptBlock (並列実行)
```

### データフロー図

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

.blg ファイルパス ----+
                      |
DataCollector --------+----> パス収集・検証 ----> relog実行 ----> FileInfo オブジェクト
                      |         |                    |               (RelogFile=true)
DataCollectorSet -----+         |                    |
                                v                    v
                         パラメータ構築         TSV/CSV/bin/SQL
                         (Type/Interval等)          ファイル
```

### 関連ファイル一覧

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