# 画面設計書 109-トレースフラグ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverのトレースフラグ管理機能（Get-DbaTraceFlag、Enable-DbaTraceFlag、Disable-DbaTraceFlag）の設計仕様を記載する。

### 本画面の処理概要

SQL Serverのグローバルトレースフラグの状態を取得・有効化・無効化するためのコマンドラインインターフェースを提供する。トレースフラグはSQL Serverの動作を変更するための診断・チューニング機能である。

**業務上の目的・背景**：トレースフラグはSQL Serverの特定の動作を変更するために使用され、パフォーマンス最適化やトラブルシューティングに活用される。例えば、TF 3226でバックアップログメッセージを抑制、TF 1117/1118でTempDB最適化、TF 4199でクエリオプティマイザ修正を有効化できる。本機能により、複数インスタンスのトレースフラグ設定の監査・標準化が効率化される。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaTraceFlag`、`Enable-DbaTraceFlag`、または `Disable-DbaTraceFlag` コマンドを実行する。

**主要な操作・処理内容**：
1. トレースフラグの取得（Get-DbaTraceFlag）：現在有効なグローバルトレースフラグの一覧
2. トレースフラグの有効化（Enable-DbaTraceFlag）：DBCC TRACEONによるフラグ有効化
3. トレースフラグの無効化（Disable-DbaTraceFlag）：DBCC TRACEOFFによるフラグ無効化

**画面遷移**：Get-DbaTraceFlagで現在のトレースフラグ状態を確認し、Enable-DbaTraceFlag/Disable-DbaTraceFlagで変更を適用する流れ。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 151 | Get-DbaTraceFlag | 主機能 | トレースフラグの取得 |
| 82 | Enable-DbaTraceFlag | 主機能 | トレースフラグの有効化 |
| 80 | Disable-DbaTraceFlag | 主機能 | トレースフラグの無効化 |

## 画面種別

コマンドラインインターフェース（取得・有効化・無効化）

## URL/ルーティング

PowerShellコマンド実行

## 入出力項目

### Get-DbaTraceFlag パラメータ

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

### Enable-DbaTraceFlag パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| TraceFlag | int[] | 必須 | 有効化するトレースフラグ番号 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Disable-DbaTraceFlag パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| TraceFlag | int[] | 必須 | 無効化するトレースフラグ番号 |
| EnableException | Switch | 任意 | 例外を有効にする |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| TraceFlag | int | トレースフラグ番号 |
| Global | bool | グローバルフラグかどうか |
| Session | bool | セッションフラグかどうか |
| Status | int | ステータス値 |

### Enable-DbaTraceFlag / Disable-DbaTraceFlag 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceServer | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| TraceFlag | int | トレースフラグ番号 |
| Status | string | 操作結果（Successful/Skipped/Failed） |
| Notes | string | 追加情報・エラーメッセージ |
| DateTime | DbaDateTime | 操作実行日時 |

## イベント仕様

### 1-Get-DbaTraceFlag実行

1. Connect-DbaInstanceで接続
2. $server.EnumActiveGlobalTraceFlags()でトレースフラグ一覧取得
3. 結果が0件の場合はVerboseメッセージを出力
4. TraceFlag指定時はWhere-Objectでフィルタ
5. 各トレースフラグについてPSCustomObjectを出力

### 2-Enable-DbaTraceFlag実行

1. Connect-DbaInstanceで接続
2. Get-DbaTraceFlagで現在有効なトレースフラグを取得
3. 各TraceFlag番号について：
   - 既に有効な場合はStatus='Skipped'で出力
   - DBCC TRACEON($tf, -1)を実行
   - 成功時はStatus='Successful'
   - 失敗時はStatus='Failed'とエラーメッセージ

### 3-Disable-DbaTraceFlag実行

1. Connect-DbaInstanceで接続
2. Get-DbaTraceFlagで現在有効なトレースフラグを取得
3. 各TraceFlag番号について：
   - 有効でない場合はStatus='Skipped'で出力
   - DBCC TRACEOFF($tf, -1)を実行
   - 成功時はStatus='Successful'
   - 失敗時はStatus='Failed'とエラーメッセージ

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaTraceFlag | - | SMO/DBCC | EnumActiveGlobalTraceFlags()実行 |
| Enable-DbaTraceFlag | - | DBCC | DBCC TRACEON実行 |
| Disable-DbaTraceFlag | - | DBCC | DBCC TRACEOFF実行 |

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

#### DBCC経由（Enable/Disable-DbaTraceFlag）

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| TRACEON | トレースフラグ | 指定番号, -1 | グローバルに有効化 |
| TRACEOFF | トレースフラグ | 指定番号, -1 | グローバルに無効化 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|----------|
| MSG001 | 情報 | "No global trace flags enabled" | トレースフラグが1つも有効でない場合 |
| MSG002 | 警告 | "The Trace flag [$tf] is already running globally." | 既に有効なフラグを有効化しようとした場合 |
| MSG003 | 警告 | "Trace Flag $tf is not currently running on $instance" | 有効でないフラグを無効化しようとした場合 |
| MSG004 | ステータス | "The Trace flag is already running." | 既に有効（Skipped時のNotes） |
| MSG005 | ステータス | "Trace Flag is not running." | 有効でない（Skipped時のNotes） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| DBCC実行失敗 | Status='Failed'、Notes=エラーメッセージで出力し、Continueで次のフラグへ |

## 備考

- トレースフラグの変更はSQL Server再起動後に失われる（メモリ内のみ）
- 永続化にはSet-DbaStartupParameterで起動パラメータに追加する必要がある
- グローバルトレースフラグは全セッションに影響（-1指定）
- Session列は既定ビューから除外されている
- 一般的なトレースフラグ：
  - 3226: バックアップログメッセージ抑制
  - 1117/1118: TempDB最適化
  - 4199: クエリオプティマイザ修正
  - 2371: 統計自動更新閾値の改善

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | 出力オブジェクトの構造（行102-110）を確認 |
| 1-2 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | 出力オブジェクトの構造（行98-106）を確認 |

**読解のコツ**: GetはGlobal/Session/Status、Enable/DisableはStatus/Notes/DateTimeを含む点に注意

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | param()ブロック（行73-80）でパラメータ定義を確認 |
| 2-2 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | param()ブロック（行77-84）でパラメータ定義を確認 |
| 2-3 | Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | param()ブロック（行69-77）でパラメータ定義を確認 |

**主要処理フロー**:
1. **行90**: $server.EnumActiveGlobalTraceFlags()でフラグ一覧取得
2. **行92-95**: 結果が0件の場合の処理
3. **行97-99**: TraceFlag指定時のフィルタ

#### Step 3: トレースフラグ有効化ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | DBCC TRACEON実行（行86-128） |

**主要処理フロー**:
- **行94**: Get-DbaTraceFlagで現在の状態取得
- **行107-113**: 既に有効な場合はSkipped
- **行116**: DBCC TRACEON($tf, -1)実行
- **行125**: 成功時はStatus='Successful'

#### Step 4: トレースフラグ無効化ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | DBCC TRACEOFF実行（行79-122） |

**主要処理フロー**:
- **行88**: Get-DbaTraceFlagで現在の状態取得
- **行100-106**: 有効でない場合はSkipped
- **行109**: DBCC TRACEOFF($tf, -1)実行
- **行117**: 成功時はStatus='Successful'

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

```
Get-DbaTraceFlag
    |
    +-- Connect-DbaInstance
    |
    +-- $server.EnumActiveGlobalTraceFlags()
    |
    +-- (TraceFlag指定時)
    |      +-- Where-Object TraceFlag -In $TraceFlag
    |
    +-- foreach ($tflag in $tflags)
           +-- PSCustomObject出力
                  +-- TraceFlag
                  +-- Global
                  +-- Session
                  +-- Status

Enable-DbaTraceFlag
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaTraceFlag (現在の状態取得)
    |
    +-- foreach ($tf in $TraceFlag)
           |
           +-- (既に有効な場合)
           |      +-- Status='Skipped'
           |      +-- Notes='The Trace flag is already running.'
           |
           +-- (有効でない場合)
                  +-- DBCC TRACEON($tf, -1)
                  +-- $server.Refresh()
                  +-- Status='Successful' または 'Failed'

Disable-DbaTraceFlag
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaTraceFlag (現在の状態取得)
    |
    +-- foreach ($tf in $TraceFlag)
           |
           +-- (有効でない場合)
           |      +-- Status='Skipped'
           |      +-- Notes='Trace Flag is not running.'
           |
           +-- (有効な場合)
                  +-- DBCC TRACEOFF($tf, -1)
                  +-- Status='Successful' または 'Failed'
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──────▶ SMO Server Object
                           |
                           v
                    (Get-DbaTraceFlag)
                    EnumActiveGlobalTraceFlags()
                           |
                           v
                    PSCustomObject ──────▶ TraceFlag, Global, Session, Status

TraceFlag[] ──────▶ (Enable-DbaTraceFlag)
                    Get-DbaTraceFlag()
                           |
                           v
                    既存チェック
                           |
                           v
                    DBCC TRACEON($tf, -1)
                           |
                           v
                    PSCustomObject ──────▶ TraceFlag, Status, Notes, DateTime

TraceFlag[] ──────▶ (Disable-DbaTraceFlag)
                    Get-DbaTraceFlag()
                           |
                           v
                    既存チェック
                           |
                           v
                    DBCC TRACEOFF($tf, -1)
                           |
                           v
                    PSCustomObject ──────▶ TraceFlag, Status, Notes, DateTime
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | ソース | トレースフラグ取得 |
| Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | ソース | トレースフラグ有効化 |
| Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | ソース | トレースフラグ無効化 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | ソース | 起動パラメータ設定（永続化用） |
