# 機能設計書 89-Find-DbaDbGrowthEvent

## 概要

本ドキュメントは、dbatools PowerShellモジュールのFind-DbaDbGrowthEvent関数の機能設計を定義する。この関数は、SQL Serverのデフォルトトレースからデータベースの自動拡張・自動縮小イベントを取得する機能を提供する。

### 本機能の処理概要

Find-DbaDbGrowthEvent は、SQL Serverのデフォルトトレースをクエリして、データベースファイルの自動拡張（Auto-Growth）および自動縮小（Auto-Shrink）イベントを検出するコマンドレットである。パフォーマンストラブルシューティングやキャパシティプランニングに必要な詳細なタイミングとサイズ変更情報を提供する。

**業務上の目的・背景**：データベースファイルの自動拡張イベントはパフォーマンス低下の主要な原因となる。自動拡張中はI/O操作がブロックされ、アプリケーションの応答性が低下する可能性がある。本機能は、いつ、どのデータベースで、どの程度の拡張が発生したかを特定することで、初期ファイルサイズの最適化やストレージ成長パターンの分析を可能にする。また、自動縮小イベントはファイルの断片化を引き起こすため、検出して対処することが重要である。

**機能の利用シーン**：
- パフォーマンス低下の原因調査（自動拡張によるI/Oブロック）
- ストレージ成長パターンの分析とキャパシティプランニング
- 初期ファイルサイズの最適化検討
- 自動縮小による断片化問題の特定
- データベース拡張を引き起こしたアプリケーションの特定

**主要な処理内容**：
1. デフォルトトレースの有効性確認
2. トレースファイルパスの取得
3. fn_trace_gettable 関数によるトレースデータの読み取り
4. イベントクラスによるフィルタリング（92/93/94/95）
5. データベースおよびイベントタイプによるフィルタリング
6. 結果の出力

**関連システム・外部連携**：
- SQL Server デフォルトトレース機能
- sys.traces システムビュー
- fn_trace_gettable システム関数
- sys.configurations（トレース設定確認用）

**権限による制御**：
- ALTER TRACE 権限または sysadmin ロールが必要
- デフォルトトレースが有効化されている必要がある

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 64 | データベースファイル成長 | 補助機能 | 成長イベントの検索 |

## 機能種別

監視 / 診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| Database | object[] | No | 対象データベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | 除外データベース | ワイルドカード対応 |
| EventType | string | No | イベントタイプ | Growth/Shrink |
| FileType | string | No | ファイルタイプ | Data/Log |
| UseLocalTime | switch | No | ローカル時刻で表示 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力: SqlInstance をパイプラインから受け取り
- SQL Server: デフォルトトレースファイル

## 出力仕様

### 出力データ

デフォルト表示プロパティ:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| EventClass | int | イベントクラス番号 |
| DatabaseName | string | データベース名 |
| Filename | string | ファイルパス |
| Duration | int | イベント期間（ミリ秒） |
| StartTime | DateTime | 開始時刻 |
| EndTime | DateTime | 終了時刻 |
| ChangeInSize | float | サイズ変更量（MB） |
| ApplicationName | string | アプリケーション名 |
| HostName | string | クライアントホスト名 |

追加プロパティ:
| 項目名 | 型 | 説明 |
|--------|-----|------|
| DatabaseId | int | データベースID |
| SessionLoginName | string | セッションログイン名 |
| SPID | int | プロセスID |
| OrderRank | int | 順序ランク |

### 出力先

- PowerShellパイプライン: PSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. 前処理（begin）
   ├─ イベントクラスリストの初期化（92-95）
   ├─ EventType/FileTypeによるフィルタリング
   └─ SQLテンプレートの準備

2. SqlInstanceのループ処理（process）
   ├─ インスタンスへの接続
   ├─ データベースリストの取得とフィルタリング
   ├─ SQLクエリの構築と実行
   └─ 結果の出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[イベントクラス初期化]
    B --> C{FileType指定?}
    C -->|Data| D[93,95を除外]
    C -->|Log| E[92,94を除外]
    C -->|No| F{EventType指定?}
    D --> F
    E --> F
    F -->|Growth| G[94,95を除外]
    F -->|Shrink| H[92,93を除外]
    F -->|No| I[フィルターなし]
    G --> J[インスタンスループ]
    H --> J
    I --> J
    J --> K[Connect-DbaInstance]
    K --> L{接続成功?}
    L -->|No| M[エラー出力、次へ]
    L -->|Yes| N[DB一覧取得]
    N --> O[DBフィルタリング]
    O --> P[SQL構築・実行]
    P --> Q[Select-DefaultView]
    Q --> R{次のInstance?}
    M --> R
    R -->|Yes| J
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトトレース必須 | デフォルトトレースが有効でない場合は結果なし | 常時 |
| BR-002 | イベントクラス定義 | 92=Data成長、93=Log成長、94=Data縮小、95=Log縮小 | 常時 |
| BR-003 | UTC変換 | UseLocalTime未指定時はUTCに変換 | UseLocalTime未指定 |
| BR-004 | サイズ計算 | IntegerData * 8.0 / 1024 でMBに変換 | 常時 |

### 計算ロジック

イベントクラス:
- 92: Data File Auto Grow
- 93: Log File Auto Grow
- 94: Data File Auto Shrink
- 95: Log File Auto Shrink

サイズ変更計算: `IntegerData * 8.0 / 1024` （ページ数からMBへ変換）

Duration計算: `Duration / 1000` （マイクロ秒からミリ秒へ変換）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定確認 | sys.configurations | SELECT | default trace enabled確認 |
| トレースパス取得 | sys.traces | SELECT | デフォルトトレースファイルパス |
| トレースデータ取得 | fn_trace_gettable | SELECT | トレースイベントデータ |

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

#### sys.configurations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | value_in_use | name = 'default trace enabled' | トレース有効確認 |

#### sys.traces

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | path | is_default = 1 | デフォルトトレースパス |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | インスタンス名・認証情報を確認 |
| TraceDisabled | 設定エラー | デフォルトトレースが無効 | トレースを有効化 |
| QueryError | 実行エラー | fn_trace_gettableの実行失敗 | 権限を確認 |

### リトライ仕様

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

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

読み取り専用操作のため、トランザクション制御は不要。

## パフォーマンス要件

- デフォルトトレースファイルのサイズに応じた読み取り時間
- 複数のトレースファイルがある場合、すべてのファイルを読み取る

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

- ALTER TRACE 権限または sysadmin ロールが必要
- SqlCredential パラメータで代替認証資格情報を安全に渡すことが可能

## 備考

- デフォルトトレースはSQL Server起動時に自動的に開始される
- トレースファイルは循環的に使用され、古いデータは上書きされる
- SQL Server Management Studio（SSMS）から抽出されたクエリを使用

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | 77-96行目の.OUTPUTS セクション |

**読解のコツ**: EventClassの値によってイベントタイプが決まる（92-95の4種類）。

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

パラメータ定義とイベントクラスフィルターを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | 128-141行目のparam()ブロック |
| 2-2 | Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | 143-174行目のbeginブロック |

**主要処理フロー**:
1. **144-145行目**: イベントクラスリストの初期化（92-95）
2. **147-172行目**: FileType/EventTypeによるイベントクラスフィルタリング
3. **174行目**: フィルター文字列の構築

#### Step 3: SQLテンプレートを理解する

動的に生成されるSQLクエリの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | 176-259行目のSQLテンプレート |

**主要処理フロー**:
- **177-178行目**: デフォルトトレース有効確認
- **184-191行目**: トレースファイルパスの取得と変換
- **193-220行目**: メインSELECTクエリ（UTC/ローカル時刻の分岐）
- **221-240行目**: トレース無効時のダミー結果
- **241-259行目**: エラーハンドリング用CATCH

#### Step 4: クエリ実行と結果処理を理解する

データベースリストとクエリ実行を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | 261-294行目のprocessブロック |

**主要処理フロー**:
- **269行目**: データベースコレクション取得
- **271-277行目**: Database/ExcludeDatabaseフィルター
- **280行目**: データベースリストのSQL形式構築
- **283行目**: _DatabaseList_プレースホルダーの置換
- **289行目**: Select-DefaultViewで表示プロパティ設定

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

```
Find-DbaDbGrowthEvent
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続の確立
    │
    ├─ $server.Databases
    │      └─ データベースコレクション取得
    │
    └─ $server.Query($sql)
           └─ トレースデータクエリ実行
               ├─ sys.configurations（トレース有効確認）
               ├─ sys.traces（パス取得）
               └─ fn_trace_gettable（データ取得）
```

### データフロー図

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

SqlInstance ───┬──▶ Connect-DbaInstance
               │           │
Database ──────┤           ▼
               │    Database取得・フィルター
ExcludeDB ─────┤           │
               │           ▼
EventType ─────┤    EventClassフィルター構築
               │    (92/93/94/95)
FileType ──────┤           │
               │           ▼
UseLocalTime ──┘    SQLテンプレート構築
                   (UTC/ローカル時刻)
                          │
                          ▼
                   fn_trace_gettable
                   クエリ実行
                          │
                          ▼
                   Select-DefaultView
                          │
                          ▼
                   PSCustomObject ──────▶ パイプライン出力
                   (EventClass,Duration,
                    ChangeInSize...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaDbGrowthEvent.ps1 | `public/Find-DbaDbGrowthEvent.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ユーティリティ |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | 表示プロパティ制御 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力関数 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータバインド確認関数 |
