# 機能設計書 163-Invoke-DbaCycleErrorLog

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Invoke-DbaCycleErrorLog`コマンドレットに関する機能設計書である。このコマンドは、現在のSQL Serverエラーログおよび/またはSQL Agentエラーログをサイクルして新しいログファイルを開始する機能を提供する。

### 本機能の処理概要

Invoke-DbaCycleErrorLogは、SQL ServerインスタンスおよびSQL Agent用の現在のエラーログファイルをアーカイブし、新しいログファイルを作成する。この操作は通常、メンテナンスウィンドウ中にログファイルサイズを管理し、トラブルシューティングのためのクリーンなベースラインを確立するために実行される。サイクルされると、現在のエラーログはアーカイブログ（errorlog.1）となり、新しいエラーログがイベントのキャプチャを開始する。

**業務上の目的・背景**：
SQL Serverのエラーログは、時間経過とともに肥大化し、ディスク容量を圧迫したり、ログの確認が困難になったりする。定期的なログサイクルにより、ログファイルサイズを管理し、特定の時点からのイベントを明確に追跡できるようになる。また、問題発生時のトラブルシューティングを効率化し、監査対応やログ分析作業を容易にする。

**機能の利用シーン**：
- 定期メンテナンス作業の一環としてのログローテーション
- トラブルシューティング前のログベースライン確立
- ログファイルサイズ管理のための定期的なサイクル
- 監査証跡の管理と保存
- デプロイメント前後のログ分離

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（最小バージョン: SQL Server 2005）
2. Type パラメータに基づくサイクル対象の決定
3. 適切なストアドプロシージャの実行
   - インスタンスログ: `sp_cycle_errorlog`
   - Agentログ: `sp_cycle_agent_errorlog`
4. 結果オブジェクトの生成と返却

**関連システム・外部連携**：
- SQL Server Database Engine
- SQL Server Agent
- msdbデータベース（Agent エラーログ用）
- masterデータベース（インスタンスエラーログ用）

**権限による制御**：
- sysadminサーバーロールのメンバーシップが必要
- SQL Server 2005以上のバージョンが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | コマンドラインからの直接実行 |

## 機能種別

システム管理 / ログ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットのSQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替資格情報 | - |
| Type | string | No | サイクルするエラーログの種類（instance、agent） | ValidateSet: 'instance', 'agent' |
| WhatIf | switch | No | 実行内容の表示のみ | - |
| Confirm | switch | No | 確認プロンプトの表示 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- コマンドライン引数
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（computer\instance） |
| LogType | string[] | サイクルされたログタイプの配列（'instance'、'agent'、または両方） |
| IsSuccessful | boolean | エラーログサイクルが成功したかどうか |
| Notes | Exception | 操作が失敗した場合の例外オブジェクト（成功時はnull） |

### 出力先

コンソール（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   ├─ Typeパラメータの検証
   ├─ SQLクエリの構築
   │   ├─ Type='agent': sp_cycle_agent_errorlog
   │   ├─ Type='instance': sp_cycle_errorlog
   │   └─ Type未指定: 両方のストアドプロシージャ
   └─ logToCycle配列の設定
2. processブロック
   ├─ FunctionInterruptのテスト
   └─ 各SqlInstanceのループ処理
       ├─ Connect-DbaInstance（MinimumVersion 9）
       ├─ ShouldProcessによる確認
       ├─ クエリの実行
       └─ 結果オブジェクトの生成
           ├─ 成功時: IsSuccessful=true, Notes=null
           └─ 失敗時: IsSuccessful=false, Notes=Exception
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Type指定あり?}
    B -->|agent| C[sp_cycle_agent_errorlog]
    B -->|instance| D[sp_cycle_errorlog]
    B -->|なし| E[両方のSP]

    C --> F[logToCycle='agent']
    D --> G[logToCycle='instance']
    E --> H[logToCycle='instance','agent']

    F --> I[SqlInstanceループ開始]
    G --> I
    H --> I

    I --> J[Connect-DbaInstance]
    J --> K{接続成功?}
    K -->|No| L[Stop-Function Continue]
    K -->|Yes| M{ShouldProcess?}

    L --> I
    M -->|No| I
    M -->|Yes| N[クエリ実行]

    N --> O{実行成功?}
    O -->|Yes| P[PSCustomObject出力 IsSuccessful=true]
    O -->|No| Q[PSCustomObject出力 IsSuccessful=false]

    P --> R{次のインスタンス?}
    Q --> S[Stop-Function Continue]
    S --> R
    R -->|Yes| I
    R -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト動作 | Type未指定時は両方のログをサイクル | Type未指定 |
| BR-002 | 最小バージョン | SQL Server 2005（バージョン9）以上が必要 | 常時 |
| BR-003 | sysadmin必須 | sysadminサーバーロールのメンバーシップが必要 | 常時 |
| BR-004 | ログアーカイブ | サイクル時、現在のログはerrorlog.1になる | 常時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| インスタンスログサイクル | master.dbo.sp_cycle_errorlog | EXEC | SQL Serverエラーログのサイクル |
| Agentログサイクル | msdb.dbo.sp_cycle_agent_errorlog | EXEC | SQL Agentエラーログのサイクル |

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

#### sp_cycle_errorlog (master)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| EXEC | - | - | パラメータなしで実行 |

#### sp_cycle_agent_errorlog (msdb)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| EXEC | - | - | パラメータなしで実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverインスタンスへの接続失敗 | Stop-Function -Continue |
| - | ExecutionError | ストアドプロシージャ実行失敗 | IsSuccessful=false、Notes=Exception |

### リトライ仕様

リトライ機能なし（エラー発生時は次のインスタンスに継続）

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

該当なし（ストアドプロシージャは内部でトランザクション管理）

## パフォーマンス要件

特に定義されていない。通常、ログサイクル操作は即座に完了する。

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

- sysadminサーバーロールが必要
- SQL認証またはWindows認証をサポート
- MFAサポートにはConnect-DbaInstanceを使用

## 備考

- ConfirmImpactは'Low'に設定（軽微な変更操作）
- SQL Server 2000はサポートされていない（MinimumVersion 9）
- ログファイルの保持数はSQL Serverの設定に依存

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | 出力PSCustomObject | 125-132行目、135-142行目 | ComputerName, InstanceName, SqlInstance, LogType, IsSuccessful, Notes |

**読解のコツ**: 成功時と失敗時で同じプロパティ構造だが、IsSuccessfulとNotesの値が異なる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaCycleErrorLog.ps1 | `public/Invoke-DbaCycleErrorLog.ps1` | 関数全体の構造とパラメータ定義 |

**主要処理フロー**:
1. **75-83行目**: パラメータ定義
2. **85-109行目**: beginブロック（SQLクエリ構築）
3. **110-146行目**: processブロック（メイン処理）

#### Step 3: クエリ構築ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | beginブロック | 85-109行目 | Type判定とSQLクエリ生成 |

**主要処理フロー**:
- **86-90行目**: Typeパラメータの検証
- **92-108行目**: switch文によるSQL構築
  - **94-97行目**: agent指定時
  - **98-101行目**: instance指定時
  - **102-107行目**: デフォルト（両方）

#### Step 4: 実行処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | processブロック | 110-146行目 | 接続、実行、結果生成 |

**主要処理フロー**:
- **114-119行目**: Connect-DbaInstance（MinimumVersion 9）
- **122-133行目**: try-catchによるクエリ実行と成功時オブジェクト生成
- **134-144行目**: catch句によるエラー処理と失敗時オブジェクト生成

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

```
Invoke-DbaCycleErrorLog
    │
    ├─ Test-Bound (Typeパラメータ検証)
    │
    ├─ Test-FunctionInterrupt
    │
    ├─ Connect-DbaInstance
    │      └─ -MinimumVersion 9 (SQL Server 2005以上)
    │
    ├─ $server.Query()
    │      ├─ sp_cycle_errorlog (master)
    │      └─ sp_cycle_agent_errorlog (msdb)
    │
    └─ Stop-Function (エラー時)
```

### データフロー図

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

SqlInstance ────────────▶ Connect-DbaInstance ──────┐
SqlCredential ──────────▶                           │
                                                    │
                         ┌──────────────────────────┘
                         │
                         ▼
Type ──────────────────▶ switch文
                         │
                         ├─ agent: sp_cycle_agent_errorlog
                         ├─ instance: sp_cycle_errorlog
                         └─ default: 両方
                               │
                               ▼
                         $server.Query($sql)
                               │
                               ▼
                         ┌───────────────────────┐
                         │ PSCustomObject生成     │──────▶ コンソール出力
                         │ - ComputerName        │
                         │ - InstanceName        │
                         │ - SqlInstance         │
                         │ - LogType             │
                         │ - IsSuccessful        │
                         │ - Notes               │
                         └───────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaCycleErrorLog.ps1 | `public/Invoke-DbaCycleErrorLog.ps1` | ソース | メイン関数定義 |
| Get-DbaErrorLog.ps1 | `public/Get-DbaErrorLog.ps1` | ソース | エラーログの取得（関連機能） |
| Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | ソース | Agentログの取得（関連機能） |
