# 機能設計書 528-Stop-DbaTrace

## 概要

本ドキュメントは、実行中の SQL Server トレースを停止する `Stop-DbaTrace` コマンドの機能設計書です。

### 本機能の処理概要

実行中の SQL Server トレースを停止する PowerShell コマンドです。sp_trace_setstatus でステータスを 0 に設定してトレースを停止します。

**業務上の目的・背景**：トラブルシューティングやパフォーマンス監視で使用中のトレースは、必要な情報を収集した後に停止する必要があります。不要に実行し続けるトレースはサーバーリソースを消費し、パフォーマンスに影響を与える可能性があります。本コマンドは、トレースを PowerShell から停止することで、自動化スクリプトや管理作業の効率化を実現します。

**機能の利用シーン**：
- トラブルシューティング完了後のトレース停止
- メンテナンスウィンドウ前のトレース停止
- サーバーリソース節約のためのトレース停止
- 複数サーバーでの一括トレース停止
- スケジュールされたトレース停止

**主要な処理内容**：
1. トレースオブジェクトの取得（パラメータまたはパイプライン）
2. デフォルトトレースの保護チェック
3. sp_trace_setstatus でトレース停止（ステータス 0）
4. Get-DbaTrace で結果を取得して出力

**関連システム・外部連携**：SQL Server Database Engine、sp_trace_setstatus システムストアドプロシージャ

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Profiler | 参照画面 | トレースの停止と同等の操作 |

## 機能種別

システム操作 / トレース管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象の SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Id | int[] | No | 停止するトレース ID | 正の整数 |
| InputObject | object[] | No | パイプラインからのトレースオブジェクト | Get-DbaTrace からの出力 |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- Get-DbaTrace からのトレースオブジェクト
- または SqlInstance と Id パラメータの組み合わせ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Server をホストするコンピュータ名 |
| InstanceName | string | SQL Server インスタンス名 |
| SqlInstance | string | 完全な SQL Server インスタンス名 |
| Id | int | トレース ID |
| Status | int | トレースステータス |
| IsRunning | bool | トレースが実行中かどうか（停止後は false） |
| Path | string | トレースファイルのパス |
| (その他) | - | Get-DbaTrace の全出力プロパティ |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力オブジェクトの取得
   └─ -InputObject がない場合、Get-DbaTrace で取得
2. 各トレースの処理ループ
   └─ 入力検証（id と Parent プロパティ確認）
   └─ サーバーオブジェクトとトレース ID 取得
3. デフォルトトレースチェック
   └─ デフォルトトレースの場合はエラーで継続
   └─ Set-DbaSpConfigure の使用を案内
4. トレース停止
   └─ ShouldProcess 確認
   └─ sp_trace_setstatus traceid, 0 実行
5. 結果取得と出力
   └─ Get-DbaTrace で最新状態を取得
   └─ 取得できない場合は手動で PSCustomObject 作成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject あり?}
    B -->|No| C[Get-DbaTrace で取得]
    B -->|Yes| D[InputObject 使用]
    C --> E[各トレースをループ]
    D --> E
    E --> F{id と Parent あり?}
    F -->|No| G[エラー・スキップ]
    F -->|Yes| H{デフォルトトレース?}
    H -->|Yes| I[警告・スキップ]
    H -->|No| J{ShouldProcess?}
    J -->|No| K[スキップ]
    J -->|Yes| L[sp_trace_setstatus 0 実行]
    L --> M[Get-DbaTrace で結果取得]
    M --> N{結果あり?}
    N -->|Yes| O[結果出力]
    N -->|No| P[手動 PSCustomObject 作成]
    P --> O
    G --> Q{次のトレース?}
    I --> Q
    K --> Q
    O --> Q
    Q -->|Yes| E
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトトレース保護 | デフォルトトレースはこの関数では停止できない | 常時 |
| BR-002 | 入力検証 | id と Parent プロパティが必要 | 常時 |
| BR-003 | 結果取得 | 停止後に Get-DbaTrace で最新状態を取得 | 常時 |
| BR-004 | フォールバック出力 | Get-DbaTrace で取得できない場合は手動で出力を作成 | Get-DbaTrace が null の場合 |

### 計算ロジック

sp_trace_setstatus のステータス値：
- 0: 停止
- 1: 開始
- 2: クローズ・削除

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トレース停止 | sys.traces | UPDATE (間接) | sp_trace_setstatus でステータス変更 |
| トレース確認 | sys.traces | SELECT | Get-DbaTrace で状態取得 |

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

#### sp_trace_setstatus

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| EXEC | traceid, status | traceid, 0 | システムストアドプロシージャ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力エラー | 不正な入力オブジェクト | Get-DbaTrace を使用 |
| - | 保護エラー | デフォルトトレースを停止しようとした | Set-DbaSpConfigure を使用 |
| - | 実行エラー | sp_trace_setstatus が失敗 | ALTER TRACE 権限を確認 |

### リトライ仕様

リトライなし

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

sp_trace_setstatus は内部的にトランザクション管理を行う

## パフォーマンス要件

- トレースの停止は即座に完了
- トレース数に比例した処理時間

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

- ALTER TRACE 権限または sysadmin が必要
- デフォルトトレースは保護されている

## 備考

- デフォルトトレースを無効にするには Set-DbaSpConfigure を使用
- SupportsShouldProcess で -WhatIf/-Confirm をサポート
- パイプラインで Get-DbaTrace と連携可能
- トレースが停止後に削除された場合、フォールバック出力を使用

---

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

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

### 推奨読解順序

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

出力は通常 Get-DbaTrace の形式ですが、フォールバック用の PSCustomObject も定義されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | 結果出力とフォールバック（128-156行目） |

**読解のコツ**: Get-DbaTrace が null の場合、手動で PSCustomObject を作成します。

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

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

**主要処理フロー**:
1. **95-103行目**: パラメータ定義
2. **104-163行目**: process ブロックでトレース停止処理

#### Step 3: 停止ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | 停止処理 |

**主要処理フロー**:
- **117-121行目**: デフォルトトレースチェック
- **123行目**: sp_trace_setstatus クエリ
- **125-156行目**: 実行と結果取得

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

```
Stop-DbaTrace
    │
    ├─ Get-DbaTrace
    │      └─ InputObject がない場合のトレース取得
    │
    ├─ Get-DbaTrace (Default)
    │      └─ デフォルトトレース取得
    │
    ├─ $server.Query("sp_trace_setstatus $traceid, 0")
    │      └─ トレース停止
    │
    ├─ Get-DbaTrace (結果)
    │      └─ 停止後の状態取得
    │
    └─ Select-DefaultView
           └─ 出力プロパティ設定（フォールバック時）
```

### データフロー図

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

SqlInstance/Id ──▶ Get-DbaTrace ─────────▶ Trace Objects
    or
InputObject ────▶ Default Check ─────────▶ Protection
                         │
                  ShouldProcess ─────────▶ Confirmation
                         │
                  sp_trace_setstatus 0 ──▶ Stop
                         │
                  Get-DbaTrace ──────────▶ Updated State
                         │                      or
                  Fallback Object ───────▶ Manual Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Stop-DbaTrace.ps1 | `public/Stop-DbaTrace.ps1` | ソース | メイン関数定義 |
| Get-DbaTrace.ps1 | `public/Get-DbaTrace.ps1` | ソース | トレース情報取得 |
