# 画面設計書 110-トレース管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverのトレース管理機能（Get-DbaTrace、Remove-DbaTrace、Start-DbaTrace、Stop-DbaTrace、Read-DbaTraceFile）の設計仕様を記載する。

### 本画面の処理概要

SQL Serverのトレース（SQL Serverプロファイラやsp_traceで作成されたトレース）を取得・開始・停止・削除し、トレースファイルを読み取るためのコマンドラインインターフェースを提供する。

**業務上の目的・背景**：SQL Serverトレースはパフォーマンス監視、セキュリティ監査、トラブルシューティングに使用される。特にデフォルトトレースは構成変更やログイン失敗などの重要イベントを自動的にキャプチャする。本機能により、トレースの管理と分析を自動化し、複数インスタンスにわたるトレースデータの収集・分析が効率化される。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaTrace`、`Remove-DbaTrace`、`Start-DbaTrace`、`Stop-DbaTrace`、または `Read-DbaTraceFile` コマンドを実行する。

**主要な操作・処理内容**：
1. トレースの取得（Get-DbaTrace）：トレース一覧と状態の取得
2. トレースの削除（Remove-DbaTrace）：停止後にトレース定義を削除
3. トレースの開始（Start-DbaTrace）：停止中のトレースを開始
4. トレースの停止（Stop-DbaTrace）：実行中のトレースを停止
5. トレースファイルの読み取り（Read-DbaTraceFile）：トレースファイルからイベントを抽出

**画面遷移**：Get-DbaTraceでトレース状態を確認し、Start/Stop/Removeで管理。Read-DbaTraceFileでトレースデータを分析。

**権限による表示制御**：全コマンドがALTER TRACE権限またはsysadmin権限を必要とする。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 524 | Get-DbaTrace | 主機能 | トレースの取得 |
| 526 | Remove-DbaTrace | 主機能 | トレースの削除 |
| 527 | Start-DbaTrace | 補助機能 | トレースの開始 |
| 528 | Stop-DbaTrace | 補助機能 | トレースの停止 |
| 525 | Read-DbaTraceFile | 補助機能 | トレースファイルの読み取り |

## 画面種別

コマンドラインインターフェース（取得・開始・停止・削除・読み取り）

## URL/ルーティング

PowerShellコマンド実行

## 入出力項目

### Get-DbaTrace パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Id | int[] | 任意 | 特定のトレースIDでフィルタ |
| Default | Switch | 任意 | デフォルトトレースのみ取得 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Remove-DbaTrace パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 任意 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Id | int[] | 任意 | 削除するトレースID |
| InputObject | object[] | 任意 | Get-DbaTraceからのパイプ入力 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Start-DbaTrace / Stop-DbaTrace パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 任意 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Id | int[] | 任意 | 対象トレースID |
| InputObject | object[] | 任意 | Get-DbaTraceからのパイプ入力 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Read-DbaTraceFile パラメータ

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

## 表示項目

### Get-DbaTrace 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Id | int | トレースID |
| Status | int | ステータス（0=停止、1=実行中、2=クローズ） |
| IsRunning | bool | 実行中フラグ |
| Path | string | トレースファイルパス |
| MaxSize | int | 最大ファイルサイズ（MB） |
| StopTime | datetime | 停止予定時刻 |
| MaxFiles | int | 最大ファイル数 |
| IsRowset | bool | 行セットフラグ |
| IsRollover | bool | ロールオーバーフラグ |
| IsShutdown | bool | シャットダウン時停止フラグ |
| IsDefault | bool | デフォルトトレースフラグ |
| BufferCount | int | バッファ数 |
| BufferSize | int | バッファサイズ（KB） |
| FilePosition | int | ファイル位置 |
| ReaderSpid | int | 読み取りSPID |
| StartTime | datetime | 開始時刻 |
| LastEventTime | datetime | 最終イベント時刻 |
| EventCount | int | イベント数 |
| DroppedEventCount | int | ドロップイベント数 |

### Remove-DbaTrace 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Id | int | 削除されたトレースID |
| Status | string | "Stopped, closed and deleted" |

### Read-DbaTraceFile 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| TextData | string | SQLテキストまたはコマンド |
| DatabaseName | string | データベース名 |
| LoginName | string | ログイン名 |
| SPID | int | セッションプロセスID |
| StartTime | datetime | イベント開始時刻 |
| EndTime | datetime | イベント終了時刻 |
| Duration | int | 所要時間（ミリ秒） |
| EventClass | int | イベントクラス番号 |
| EventSequence | int | イベントシーケンス番号 |
| （他多数） | - | fn_trace_gettableの全列 |

## イベント仕様

### 1-Get-DbaTrace実行

1. Connect-DbaInstance（MinimumVersion 9）で接続
2. sys.tracesからトレース情報をSELECT
3. Id指定時はWHERE句でフィルタ
4. Default指定時はis_default=trueでフィルタ
5. RemotePathをJoin-AdminUncで生成
6. PSCustomObjectとして出力

### 2-Remove-DbaTrace実行

1. InputObject未指定時はGet-DbaTraceを実行
2. デフォルトトレースの場合はエラー（Set-DbaSpConfigureで無効化を案内）
3. sp_trace_setstatus $id, 0でトレース停止
4. sp_trace_setstatus $id, 2でトレース削除
5. PSCustomObjectとして出力

### 3-Start-DbaTrace実行

1. InputObject未指定時はGet-DbaTraceを実行
2. デフォルトトレースの場合はエラー（Set-DbaSpConfigureで有効化を案内）
3. sp_trace_setstatus $id, 1でトレース開始
4. Get-DbaTraceで更新後の状態を取得して出力

### 4-Stop-DbaTrace実行

1. InputObject未指定時はGet-DbaTraceを実行
2. デフォルトトレースの場合はエラー（Set-DbaSpConfigureで無効化を案内）
3. sp_trace_setstatus $id, 0でトレース停止
4. Get-DbaTraceで更新後の状態を取得して出力

### 5-Read-DbaTraceFile実行

1. Connect-DbaInstance（MinimumVersion 9）で接続
2. Path未指定時はデフォルトトレースパスを取得
3. Test-DbaPathでファイル存在確認
4. フィルタパラメータからWHERE句を構築
5. fn_trace_gettable('$file', DEFAULT)でトレースデータ取得
6. DataRowとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaTrace | sys.traces | SELECT | トレース情報の読み取り |
| Remove-DbaTrace | - | sp_trace_setstatus | トレースの停止・削除 |
| Start-DbaTrace | - | sp_trace_setstatus | トレースの開始 |
| Stop-DbaTrace | - | sp_trace_setstatus | トレースの停止 |
| Read-DbaTraceFile | - | fn_trace_gettable | トレースファイル読み取り |

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

#### sp_trace_setstatus経由

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| 停止 | trace_id, status | id, 0 | トレースを停止 |
| 開始 | trace_id, status | id, 1 | トレースを開始 |
| 削除 | trace_id, status | id, 2 | トレース定義を削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|----------|
| MSG001 | エラー | "The default trace on $server cannot be stopped. Use Set-DbaSpConfigure to turn it off." | デフォルトトレースを停止しようとした場合 |
| MSG002 | エラー | "The default trace on $server cannot be started. Use Set-DbaSpConfigure to turn it on." | デフォルトトレースを開始しようとした場合 |
| MSG003 | エラー | "Input is of the wrong type. Use Get-DbaTrace." | 不正な入力オブジェクトの場合 |
| MSG004 | 警告 | "Path does not exist" | トレースファイルが存在しない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| sys.tracesクエリ失敗 | Stop-Functionでエラー出力 |
| sp_trace_setstatus失敗 | Stop-Functionでエラー出力し、Continueで次のトレースへ |
| トレースファイル不存在 | 警告出力し、Continueで次のファイルへ |

## 備考

- デフォルトトレース（通常ID=1）はStart/Stop/Removeできない（Set-DbaSpConfigureを使用）
- トレースファイルの拡張子は.trc
- fn_trace_gettableはSQL Server 2005以上で利用可能
- トレースはSQL Serverプロファイラの代替として使用される
- Extended Events（SQL Server 2008以上）への移行が推奨されている

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | sys.tracesの列とPSCustomObjectの対応（行98, 130-156）を確認 |

**読解のコツ**: sys.tracesの列名とプロパティ名の対応関係を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | param()ブロック（行86-93）でパラメータ定義を確認 |
| 2-2 | Remove-DbaTrace.ps1 | `public/Remove-DbaTrace.ps1` | param()ブロック（行78-85）でパラメータ定義を確認 |
| 2-3 | Start-DbaTrace.ps1 | `public/Start-DbaTrace.ps1` | param()ブロック（行101-109）でパラメータ定義を確認 |
| 2-4 | Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | param()ブロック（行96-103）でパラメータ定義を確認 |
| 2-5 | Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | param()ブロック（行267-286）でパラメータ定義を確認 |

**主要処理フロー**:
1. **行98**: sys.tracesからSELECT
2. **行100-103**: Id指定時のWHERE句追加
3. **行119-121**: Default指定時のフィルタ

#### Step 3: トレース操作ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaTrace.ps1 | `public/Remove-DbaTrace.ps1` | sp_trace_setstatus呼び出し（行105-113） |
| 3-2 | Start-DbaTrace.ps1 | `public/Start-DbaTrace.ps1` | sp_trace_setstatus呼び出し（行129-133） |
| 3-3 | Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | sp_trace_setstatus呼び出し（行123-128） |

**主要処理フロー**:
- **Remove行105-106**: sp_trace_setstatus $id, 0 (停止) + $id, 2 (削除)
- **Start行129**: sp_trace_setstatus $id, 1 (開始)
- **Stop行123**: sp_trace_setstatus $id, 0 (停止)

#### Step 4: トレースファイル読み取りロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | WHERE句構築とfn_trace_gettable呼び出し（行288-385） |

**主要処理フロー**:
- **行289-347**: フィルタパラメータからWHERE句構築
- **行357-361**: Path未指定時はデフォルトトレースパス取得
- **行373-375**: fn_trace_gettable呼び出し

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

```
Get-DbaTrace
    |
    +-- Connect-DbaInstance -MinimumVersion 9
    |
    +-- sys.traces SELECT
    |      +-- (Id指定時) WHERE id IN (...)
    |
    +-- (Default指定時)
    |      +-- Where-Object is_default
    |
    +-- Join-AdminUnc (RemotePath生成)
    |
    +-- PSCustomObject出力

Remove-DbaTrace
    |
    +-- (InputObject未指定時)
    |      +-- Get-DbaTrace
    |
    +-- デフォルトトレースチェック
    |
    +-- sp_trace_setstatus $id, 0  (停止)
    |
    +-- sp_trace_setstatus $id, 2  (削除)
    |
    +-- PSCustomObject出力

Start-DbaTrace / Stop-DbaTrace
    |
    +-- (InputObject未指定時)
    |      +-- Get-DbaTrace
    |
    +-- デフォルトトレースチェック
    |
    +-- sp_trace_setstatus $id, 1/0  (開始/停止)
    |
    +-- Get-DbaTrace (更新後状態)

Read-DbaTraceFile
    |
    +-- Connect-DbaInstance -MinimumVersion 9
    |
    +-- (Path未指定時)
    |      +-- デフォルトトレースパス取得
    |
    +-- Test-DbaPath (ファイル存在確認)
    |
    +-- WHERE句構築
    |      +-- Database/Login/Spid/EventClass等
    |
    +-- fn_trace_gettable('$file', DEFAULT)
    |
    +-- DataRow出力
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──────▶ SMO Server Object
                           |
                           v
                    (Get-DbaTrace)
                    sys.traces SELECT
                           |
                           v
                    PSCustomObject ──────▶ トレース情報

Id ────────────────▶ (Remove-DbaTrace)
                    sp_trace_setstatus 0, 2
                           |
                           v
                    PSCustomObject ──────▶ 削除結果

Id ────────────────▶ (Start/Stop-DbaTrace)
                    sp_trace_setstatus 1/0
                           |
                           v
                    Get-DbaTrace ──────▶ 更新後状態

Path ──────────────▶ (Read-DbaTraceFile)
Database               |
Login                  v
Spid            fn_trace_gettable
EventClass             |
...                    v
                    DataRow ──────▶ トレースイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | ソース | トレース取得 |
| Remove-DbaTrace.ps1 | `public/Remove-DbaTrace.ps1` | ソース | トレース削除 |
| Start-DbaTrace.ps1 | `public/Start-DbaTrace.ps1` | ソース | トレース開始 |
| Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | ソース | トレース停止 |
| Read-DbaTraceFile.ps1 | `public/Read-DbaTraceFile.ps1` | ソース | トレースファイル読み取り |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認 |
| Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | ソース | デフォルトトレース設定用 |
