# 機能設計書 82-Enable-DbaTraceFlag

## 概要

本ドキュメントは、dbatools PowerShellモジュールのEnable-DbaTraceFlag関数の機能設計を定義する。この関数は、SQL Serverインスタンスでグローバルトレースフラグを有効化するための機能を提供する。

### 本機能の処理概要

Enable-DbaTraceFlag は、DBCC TRACEON コマンドを使用して、SQL Server インスタンスのグローバルレベルでトレースフラグを有効化するコマンドレットである。トレースフラグは、SQL Serverの動作を変更したり、特定の診断情報を有効にしたりするために使用される。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題のトラブルシューティング、特定の動作の有効化、推奨されるトレースフラグの適用など、データベース管理者がSQL Serverの動作をカスタマイズする際にトレースフラグが使用される。例えば、トレースフラグ3226はバックアップログメッセージを抑制し、1117/1118はtempdbの最適化に使用され、4199はクエリオプティマイザの修正を有効にする。本機能は、これらのトレースフラグを効率的に複数のインスタンスに適用するための自動化ツールを提供する。

**機能の利用シーン**：
- パフォーマンス問題の診断時に特定のトレースフラグを一時的に有効化
- Microsoftが推奨するトレースフラグを本番環境に適用
- 複数のSQL Serverインスタンスに一括でトレースフラグを設定
- tempdb最適化のためのトレースフラグ設定（SQL Server 2016以前）
- クエリオプティマイザの修正を有効化するためのトレースフラグ設定

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 現在有効なトレースフラグの取得（重複チェック用）
3. 指定されたトレースフラグが既に有効かどうかの確認
4. DBCC TRACEON コマンドの実行によるトレースフラグの有効化
5. 操作結果の出力（成功、スキップ、失敗）

**関連システム・外部連携**：
- SQL Server Database Engine との直接通信
- DBCC TRACEON システムコマンドの実行
- Get-DbaTraceFlag 関数との連携（現在の状態確認）

**権限による制御**：
- DBCC TRACEON コマンドの実行には sysadmin 固定サーバーロールのメンバーシップが必要
- または ALTER TRACE 権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 109 | トレースフラグ | 主機能 | トレースフラグの有効化 |

## 機能種別

サーバー設定 / トレースフラグ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| TraceFlag | int[] | Yes | 有効化するトレースフラグ番号 | 整数配列 |
| WhatIf | switch | No | 実行内容のプレビュー表示 | - |
| Confirm | switch | No | 実行前の確認プロンプト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力: SqlInstance パラメータがパイプラインから受け取り可能
- 直接指定: SqlInstance と TraceFlag パラメータを直接指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SourceServer | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（サービス名） |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| TraceFlag | int | 処理対象のトレースフラグ番号 |
| Status | string | 操作ステータス（Successful/Skipped/Failed） |
| Notes | string | 操作結果の詳細情報またはエラーメッセージ |
| DateTime | DbaDateTime | 操作実行日時 |

### 出力先

- PowerShellパイプライン: PSCustomObjectとして出力
- コンソール出力: 結果オブジェクトの表形式表示

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ 必須パラメータの確認

2. SqlInstanceの処理ループ
   └─ 各インスタンスへの接続確立（Connect-DbaInstance）
   └─ 現在有効なトレースフラグの取得（Get-DbaTraceFlag）

3. TraceFlagの処理ループ
   ├─ 結果オブジェクトの初期化
   ├─ 既に有効かどうかのチェック
   │   ├─ 有効な場合: Status='Skipped', 警告出力
   │   └─ 未有効な場合: DBCC TRACEON実行
   ├─ 実行結果の反映
   └─ 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスへ接続]
    B --> C{接続成功?}
    C -->|No| D[エラー出力して次へ]
    C -->|Yes| E[現在のトレースフラグ取得]
    E --> F[TraceFlagループ開始]
    F --> G{既に有効?}
    G -->|Yes| H[Status=Skipped]
    G -->|No| I{ShouldProcess確認}
    I -->|No| J[次のTraceFlag]
    I -->|Yes| K[DBCC TRACEON実行]
    K --> L{成功?}
    L -->|Yes| M[Status=Successful]
    L -->|No| N[Status=Failed]
    H --> O[結果出力]
    M --> O
    N --> O
    O --> P{次のTraceFlag?}
    P -->|Yes| F
    P -->|No| Q{次のInstance?}
    Q -->|Yes| B
    Q -->|No| R[終了]
    D --> Q
    J --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 重複有効化防止 | 既に有効なトレースフラグはスキップ | 常時 |
| BR-002 | グローバルスコープ | トレースフラグはグローバルレベル（-1）で有効化 | 常時 |
| BR-003 | 非永続化 | SQL Server再起動後はトレースフラグが無効に戻る | 常時 |
| BR-004 | 個別処理 | 各トレースフラグは個別にDBCC TRACEONを実行 | 常時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DBCC TRACEON | N/A | システムコマンド | グローバルトレースフラグの有効化 |

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

本機能はテーブル操作を行わない。DBCC TRACEON システムコマンドを使用してSQL Serverのランタイム設定を変更する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | インスタンス名・認証情報を確認 |
| DBCCError | 実行エラー | DBCC TRACEONの実行失敗 | 権限を確認、有効なトレースフラグ番号か確認 |

### リトライ仕様

自動リトライは実装されていない。エラー発生時はStop-Functionで処理を停止し、次のトレースフラグまたはインスタンスの処理に移行する。

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

DBCC TRACEONはトランザクション制御外のシステムコマンドである。即座に効果が発生し、ロールバックは不可能。

## パフォーマンス要件

- 各トレースフラグの有効化は即座に完了する
- 複数のトレースフラグを指定した場合、個別に処理されるため、数に比例した時間がかかる

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

- SqlCredential パラメータで代替認証資格情報を安全に渡すことが可能
- DBCC TRACEON の実行には sysadmin ロールまたは ALTER TRACE 権限が必要
- 一部のトレースフラグはセキュリティに影響を与える可能性があるため、適用前に確認が必要

## 備考

- 変更は SQL Server 再起動後に失われる
- 永続化するには Set-DbaStartupParameter でスタートアップパラメータに追加する必要がある
- 無効化するには Disable-DbaTraceFlag を使用する
- 現在の状態確認には Get-DbaTraceFlag を使用する

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を把握する。

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

**読解のコツ**: TraceFlagInfoという名前の一時オブジェクトを作成し、処理結果に応じてStatusとNotesプロパティを更新していく。

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

コマンドの入口となるパラメータ定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | 76-84行目のparam()ブロックでパラメータ構造を理解 |

**主要処理フロー**:
1. **78-79行目**: SqlInstanceパラメータ（Mandatory、パイプライン対応）
2. **80行目**: SqlCredentialパラメータ
3. **81-82行目**: TraceFlagパラメータ（Mandatory、整数配列）
4. **83行目**: EnableExceptionパラメータ

#### Step 3: 接続処理と事前チェックを理解する

SQL Serverへの接続と現在のトレースフラグ状態確認を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | 86-94行目の接続とトレースフラグ取得 |

**主要処理フロー**:
- **88-92行目**: Connect-DbaInstanceで接続確立。失敗時はStop-FunctionでContinue
- **94行目**: Get-DbaTraceFlagで現在有効なトレースフラグを取得

#### Step 4: トレースフラグ有効化処理を理解する

各トレースフラグの有効化ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | 97-128行目のトレースフラグ処理ループ |

**主要処理フロー**:
- **98-106行目**: 結果オブジェクトの初期化（PSCustomObject作成）
- **107-113行目**: 既に有効なトレースフラグのスキップ処理
- **114行目**: ShouldProcess確認（WhatIf/Confirm対応）
- **116行目**: DBCC TRACEON($tf, -1) コマンドの構築
- **117行目**: $server.Query() でコマンド実行
- **118行目**: サーバーのリフレッシュ
- **119-124行目**: エラーハンドリング
- **125-126行目**: 成功時のステータス設定と結果出力

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

```
Enable-DbaTraceFlag
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続の確立
    │
    ├─ Get-DbaTraceFlag
    │      └─ 現在有効なトレースフラグの取得
    │
    └─ $server.Query("DBCC TRACEON($tf, -1)")
           └─ トレースフラグの有効化
```

### データフロー図

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

SqlInstance ───┬──▶ Connect-DbaInstance
               │           │
TraceFlag ─────┘           ▼
                    Get-DbaTraceFlag
                    (現在の状態取得)
                           │
                           ▼
                    ┌──────┴──────┐
                    │ 既に有効?   │
                    └──────┬──────┘
                           │
                   Yes ────┼──── No
                     │     │      │
              Skipped      │      │
                           │      ▼
                           │  DBCC TRACEON
                           │      │
                           │  ┌───┴───┐
                           │  │ 成功? │
                           │  └───┬───┘
                           │      │
                           │  Yes─┼─No
                           │   │  │  │
                           │ Succ │ Fail
                           │      │
                           ▼      ▼
                    PSCustomObject ──────▶ パイプライン出力
                    (Status/Notes付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | ソース | メイン関数定義 |
| Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | ソース | トレースフラグ無効化（対になる機能） |
| Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | ソース | トレースフラグ状態取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ユーティリティ |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力関数 |
