# 機能設計書 524-Get-DbaTrace

## 概要

本ドキュメントは、SQL Server トレース情報を取得する `Get-DbaTrace` コマンドの機能設計書です。

### 本機能の処理概要

SQL Server インスタンス上で設定されているトレースの詳細情報（ステータス、ファイルパス、設定詳細など）を取得する PowerShell コマンドです。sys.traces システムビューをクエリして情報を返します。

**業務上の目的・背景**：SQL Server トレースは、パフォーマンス分析、セキュリティ監査、トラブルシューティングのための重要な機能です。トレースの状態を監視し、デフォルトトレースファイルの場所を特定することは、コンプライアンス監査やインシデント調査に不可欠です。本コマンドは、トレース設定のインベントリ取得と状態監視を PowerShell から効率的に行うことを可能にします。

**機能の利用シーン**：
- トレースアクティビティの監視
- トレース設定の監査と文書化
- デフォルトトレースファイルの場所特定
- トラブルシューティング時のトレース状態確認
- コンプライアンスレポート生成

**主要な処理内容**：
1. SQL Server インスタンスへの接続確立
2. sys.traces システムビューからトレース情報を取得
3. フィルタリング（ID または Default 指定時）
4. リモートファイルパスの計算（Admin UNC パス）
5. 結果オブジェクトの生成と出力

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Profiler | 参照画面 | トレース情報の視覚的な確認と同等 |

## 機能種別

情報取得 / 監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象の SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Id | int[] | No | 取得するトレース ID | 正の整数 |
| Default | switch | No | デフォルトトレースのみ取得 | - |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- sys.traces システムビュー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server をホストするコンピュータ名 |
| InstanceName | string | SQL Server インスタンス名 |
| SqlInstance | string | 完全な SQL Server インスタンス名 |
| Id | int | トレース ID |
| Status | int | トレースステータス（0=停止, 1=実行中, 2=クローズ） |
| IsRunning | bool | トレースが実行中かどうか |
| Path | string | トレースファイルのパス |
| RemotePath | string | Admin UNC パス |
| MaxSize | int | 最大ファイルサイズ（MB） |
| StopTime | DateTime | 停止予定時刻 |
| MaxFiles | int | 最大ファイル数 |
| IsRowset | bool | 行セットとして出力するか |
| IsRollover | bool | ロールオーバーが有効か |
| IsShutdown | bool | シャットダウン時に停止するか |
| IsDefault | bool | デフォルトトレースか |
| BufferCount | int | バッファ数 |
| BufferSize | int | バッファサイズ（KB） |
| FilePosition | bigint | 現在のファイル位置 |
| ReaderSpid | int | 読み取り中の SPID |
| StartTime | DateTime | 開始時刻 |
| LastEventTime | DateTime | 最後のイベント時刻 |
| EventCount | bigint | イベント数 |
| DroppedEventCount | bigint | ドロップされたイベント数 |

### 出力先

- PowerShell パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQL クエリの構築
   └─ sys.traces から全カラムを選択
   └─ -Id 指定時は WHERE 句を追加
2. SQL Server インスタンスへの接続
   └─ Connect-DbaInstance を使用（MinimumVersion 9）
3. クエリ実行
   └─ $server.Query($sql)
4. 結果フィルタリング
   └─ -Default 指定時は is_default = true のみ
5. 各行の処理
   └─ リモートパス計算（Join-AdminUnc）
   └─ PSCustomObject 作成
6. 結果出力
   └─ Select-DefaultView でプロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{-Id 指定?}
    B -->|Yes| C[WHERE id IN 追加]
    B -->|No| D[全トレース取得]
    C --> E[SQL Server 接続]
    D --> E
    E --> F{接続成功?}
    F -->|No| G[エラー終了]
    F -->|Yes| H[クエリ実行]
    H --> I{-Default 指定?}
    I -->|Yes| J[is_default フィルタ]
    I -->|No| K[全結果処理]
    J --> L[各行をループ]
    K --> L
    L --> M{Path あり?}
    M -->|Yes| N[Admin UNC 計算]
    M -->|No| O[RemotePath = null]
    N --> P[PSCustomObject 作成]
    O --> P
    P --> Q{次の行?}
    Q -->|Yes| L
    Q -->|No| R[Select-DefaultView]
    R --> S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005 (Version 9) 以上が必要 | 常時 |
| BR-002 | ステータス値 | 0=停止, 1=実行中, 2=クローズ | 常時 |
| BR-003 | IsRunning 計算 | status == 1 で true | 常時 |
| BR-004 | Admin UNC パス | Path が存在する場合のみ計算 | Path が空でない場合 |

### 計算ロジック

- IsRunning = (Status == 1)
- RemotePath = Join-AdminUnc -servername $server.ComputerName -filepath $row.path

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トレース取得 | sys.traces | SELECT | トレース情報の取得 |

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

#### sys.traces

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, status, path, max_size, stop_time, max_files, is_rowset, is_rollover, is_shutdown, is_default, buffer_count, buffer_size, file_position, reader_spid, start_time, last_event_time, event_count, dropped_event_count | 全トレースまたは指定 ID | 直接 T-SQL クエリ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | 接続情報を確認 |
| - | バージョンエラー | SQL Server 2005 未満 | SQL Server 2005 以上を使用 |
| - | クエリエラー | sys.traces からの取得失敗 | ALTER TRACE 権限を確認 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- sys.traces は軽量なシステムビューのため高速に完了
- トレース数に比例した処理時間

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

- ALTER TRACE 権限または sysadmin が必要
- トレースファイルパスの露出に注意

## 備考

- Microsoft.SqlServer.Management.Trace.TraceServer クラスは x86 PowerShell が必要なため T-SQL を使用
- デフォルトトレースは通常 ID 1

---

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

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

### 推奨読解順序

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

出力は PSCustomObject で、sys.traces の全カラムを含みます。

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

**読解のコツ**: sys.traces のカラム名がほぼそのまま出力プロパティになっています。

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

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

**主要処理フロー**:
1. **85-93行目**: パラメータ定義
2. **94-104行目**: begin ブロックで SQL クエリ構築
3. **105-158行目**: process ブロックでクエリ実行と結果処理

#### Step 3: クエリ構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | SQL クエリ構築 |

**主要処理フロー**:
- **97-98行目**: 基本 SELECT 文
- **100-103行目**: -Id 指定時の WHERE 句追加

#### Step 4: 結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | 結果処理 |

**主要処理フロー**:
- **119-121行目**: -Default フィルタ適用
- **123-128行目**: RemotePath 計算
- **130-157行目**: PSCustomObject 作成と出力

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

```
Get-DbaTrace
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO 接続確立（MinimumVersion 9）
    │
    ├─ $server.Query($sql)
    │      └─ sys.traces クエリ実行
    │
    ├─ Join-AdminUnc
    │      └─ リモートパス計算
    │
    └─ Select-DefaultView
           └─ 出力プロパティ設定
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server Object
                         │
Id ────────────▶ SQL Query Build ──────▶ T-SQL String
                         │
Default ───────▶ Query Execute ────────▶ DataRows
                         │
                  Result Filter ───────▶ Filtered Rows
                         │
                  PSCustomObject ──────▶ Pipeline Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Join-AdminUnc.ps1 | `private/functions/Join-AdminUnc.ps1` | ソース | Admin UNC パス計算 |
