# 機能設計書 525-Read-DbaTraceFile

## 概要

本ドキュメントは、SQL Server トレースファイルを解析してイベントを抽出する `Read-DbaTraceFile` コマンドの機能設計書です。

### 本機能の処理概要

SQL Server トレースファイル（.trc）を fn_trace_gettable 関数を使用して読み取り、セキュリティ監査やパフォーマンス分析のためのイベントデータを PowerShell オブジェクトとして返します。

**業務上の目的・背景**：SQL Server トレースファイルには、データベースアクティビティの詳細な記録が含まれています。セキュリティインシデントの調査、パフォーマンス問題の分析、コンプライアンスデータの抽出、スキーマ変更の追跡など、様々な目的でこれらのファイルを解析する必要があります。本コマンドは、SQL Server のデフォルトトレースや手動作成されたトレースファイルを PowerShell から効率的に解析し、フィルタリングやレポート生成を可能にします。

**機能の利用シーン**：
- ログイン失敗の調査（セキュリティ侵害分析）
- パフォーマンス問題の原因クエリ特定
- DDL 変更履歴の追跡（変更管理）
- コンプライアンス監査レポートの生成
- 特定アプリケーションのアクティビティ分析

**主要な処理内容**：
1. SQL Server インスタンスへの接続確立
2. トレースファイルパスの決定（指定なしの場合はデフォルトトレース）
3. フィルター条件の構築（WHERE 句）
4. fn_trace_gettable を使用したトレース読み取り
5. イベントデータの出力

**関連システム・外部連携**：SQL Server Database Engine、ファイルシステム、fn_trace_gettable 関数

**権限による制御**：ALTER TRACE 権限または sysadmin 固定サーバーロールのメンバーシップが必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Profiler | 参照画面 | トレースファイルの視覚的な分析と同等 |

## 機能種別

情報取得 / 監査・分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象の SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Path | string[] | No | トレースファイルのパス | 省略時はデフォルトトレース |
| Database | string[] | No | データベース名でフィルタ | - |
| Login | string[] | No | ログイン名でフィルタ | - |
| Spid | int[] | No | SPID でフィルタ | - |
| EventClass | string[] | No | イベントクラスでフィルタ | - |
| ObjectType | string[] | No | オブジェクトタイプでフィルタ | - |
| ErrorId | int[] | No | エラー番号でフィルタ | - |
| EventSequence | int[] | No | イベントシーケンスでフィルタ | - |
| TextData | string[] | No | SQL テキストでフィルタ（LIKE） | - |
| ApplicationName | string[] | No | アプリケーション名でフィルタ（LIKE） | - |
| ObjectName | string[] | No | オブジェクト名でフィルタ（LIKE） | - |
| Where | string | No | カスタム WHERE 句 | WHERE キーワード不要 |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- fn_trace_gettable システム関数
- sys.traces（デフォルトトレースパス取得用）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server をホストするコンピュータ名 |
| InstanceName | string | SQL Server インスタンス名 |
| SqlInstance | string | 完全な SQL Server インスタンス名 |
| TextData | nvarchar | SQL ステートメントまたはコマンドテキスト |
| DatabaseName | string | データベース名 |
| LoginName | string | ログイン名 |
| SPID | int | セッションプロセス ID |
| StartTime | DateTime | イベント開始時刻 |
| EndTime | DateTime | イベント終了時刻 |
| Duration | bigint | 期間（ミリ秒） |
| Reads | bigint | 論理読み取り数 |
| Writes | bigint | 論理書き込み数 |
| CPU | int | CPU 時間（ミリ秒） |
| EventClass | int | イベントクラス番号 |
| EventSequence | bigint | イベントシーケンス番号 |
| ApplicationName | string | クライアントアプリケーション名 |
| HostName | string | クライアントコンピュータ名 |
| ObjectName | string | オブジェクト名 |
| ObjectType | int | オブジェクトタイプ |
| Error | int | エラー番号 |
| (その他多数) | - | fn_trace_gettable の全カラム |

### 出力先

- PowerShell パイプライン出力（System.Data.DataRow）

## 処理フロー

### 処理シーケンス

```
1. WHERE 句の構築
   └─ -Where 指定時: そのまま使用
   └─ フィルターパラメータから構築
      └─ Database → databasename in (...)
      └─ Login → LoginName in (...)
      └─ Spid → Spid in (...)
      └─ EventClass → EventClass in (...)
      └─ ObjectType → ObjectType in (...)
      └─ ErrorId → Error in (...)
      └─ EventSequence → EventSequence in (...)
      └─ TextData → TextData like (...)
      └─ ApplicationName → ApplicationName like (...)
      └─ ObjectName → ObjectName like (...)
2. SQL Server インスタンスへの接続
   └─ Connect-DbaInstance（MinimumVersion 9）
3. トレースファイルパスの決定
   └─ -Path 指定時: そのパスを使用
   └─ 未指定時: sys.traces からデフォルトトレースパス取得
4. 各ファイルの処理
   └─ Test-DbaPath でファイル存在確認
   └─ fn_trace_gettable でクエリ実行
5. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{-Where 指定?}
    B -->|Yes| C[Where = 指定値]
    B -->|No| D{フィルター指定?}
    D -->|Yes| E[フィルターから WHERE 構築]
    D -->|No| F[WHERE なし]
    C --> G[SQL Server 接続]
    E --> G
    F --> G
    G --> H{接続成功?}
    H -->|No| I[エラー終了]
    H -->|Yes| J{-Path 指定?}
    J -->|Yes| K[指定パス使用]
    J -->|No| L[デフォルトトレース取得]
    K --> M[各ファイルをループ]
    L --> M
    M --> N[Test-DbaPath]
    N --> O{存在?}
    O -->|No| P[警告・スキップ]
    O -->|Yes| Q[fn_trace_gettable クエリ]
    Q --> R[結果出力]
    P --> S{次のファイル?}
    R --> S
    S -->|Yes| M
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005 (Version 9) 以上が必要 | 常時 |
| BR-002 | デフォルトトレース | -Path 未指定時は is_default=1 のトレースを使用 | -Path 未指定時 |
| BR-003 | LIKE フィルター | TextData, ApplicationName, ObjectName は LIKE 演算子使用 | 該当パラメータ指定時 |
| BR-004 | IN フィルター | Database, Login, Spid, EventClass 等は IN 演算子使用 | 該当パラメータ指定時 |
| BR-005 | ファイル存在確認 | 処理前に Test-DbaPath でファイル存在確認 | 常時 |

### 計算ロジック

フィルター構築ロジック:
- 文字列配列は `','` で結合して IN 句に
- LIKE パターンは `%` で囲んで部分一致

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| デフォルトトレース取得 | sys.traces | SELECT | is_default=1 のパス取得 |
| トレース読み取り | fn_trace_gettable | SELECT | トレースファイル読み取り |

### テーブル別操作詳細

#### fn_trace_gettable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全カラム + SERVERPROPERTY | WHERE 句でフィルタ | テーブル値関数 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | 接続情報を確認 |
| - | バージョンエラー | SQL Server 2005 未満 | SQL Server 2005 以上を使用 |
| - | ファイルエラー | トレースファイルが存在しない | ファイルパスを確認 |
| - | クエリエラー | fn_trace_gettable が失敗 | ALTER TRACE 権限を確認 |

### リトライ仕様

リトライなし（読み取り専用操作）

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

読み取り専用操作のためトランザクションなし

## パフォーマンス要件

- トレースファイルサイズに比例した処理時間
- 大きなファイルではフィルターの使用を推奨

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

- ALTER TRACE 権限または sysadmin が必要
- 機密情報を含む可能性があるトレースデータの取り扱いに注意

## 備考

- fn_trace_gettable の第2引数 DEFAULT は全ロールオーバーファイルを読み取る
- パイプラインで Get-DbaTrace と連携可能

---

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

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

### 推奨読解順序

#### Step 1: フィルター構築ロジックを理解する

WHERE 句の動的構築が本関数の重要な部分です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | フィルター構築（288-347行目） |

**読解のコツ**: 各フィルターパラメータが SQL の WHERE 句にどう変換されるかを確認します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | 関数定義とパラメータ |

**主要処理フロー**:
1. **266-286行目**: パラメータ定義
2. **288-347行目**: begin ブロックで WHERE 構築
3. **349-385行目**: process ブロックでクエリ実行

#### Step 3: トレースファイル処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | ファイル処理ロジック |

**主要処理フロー**:
- **357-361行目**: パス決定（指定なしはデフォルトトレース）
- **366-371行目**: ファイル存在確認
- **373-382行目**: fn_trace_gettable クエリ実行

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

```
Read-DbaTraceFile
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO 接続確立（MinimumVersion 9）
    │
    ├─ $server.ConnectionContext.ExecuteScalar
    │      └─ デフォルトトレースパス取得
    │
    ├─ Test-DbaPath
    │      └─ ファイル存在確認
    │
    └─ $server.Query($sql)
           └─ fn_trace_gettable クエリ実行
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server Object
                         │
Path ──────────▶ Path Decision ────────▶ Trace File Path
                         │
Filter Params ─▶ WHERE Build ──────────▶ WHERE Clause
                         │
                  fn_trace_gettable ───▶ Trace Events
                         │
                  Add Properties ──────▶ DataRow[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | ソース | メイン関数定義 |
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | ソース | トレース情報取得（パイプライン連携） |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | ファイル存在確認 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
