# 機能設計書 490-Get-DbaAgentLog

## 概要

本ドキュメントは、SQL Server Agent のエラーログエントリを取得する Get-DbaAgentLog 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentLog は、対象インスタンスから SQL Server Agent のエラーログエントリを取得し、Agent サービスのアクティビティ、ジョブ失敗、システムイベントに関する詳細情報を提供する機能である。Agent の履歴エラーログ（番号 0-9、0 が最新）にアクセスでき、SQL Server Management Studio を手動でナビゲートしたりシステムビューをクエリしたりする必要がない。

**業務上の目的・背景**：SQL Server Agent のエラーログは、ジョブ失敗のトラブルシューティング、Agent サービスの健全性監視、自動化プロセスのコンプライアンス監査において不可欠な情報源である。複数サーバーにわたるログの一括取得や、特定期間のログ分析を自動化することで、運用効率を向上させる。

**機能の利用シーン**：
- ジョブ失敗の原因調査
- Agent サービスの起動/停止履歴確認
- システムイベントの監査
- 複数サーバーのログ一括取得
- 過去のログファイルの分析

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. LogNumber パラメータによるログファイル指定
3. ReadErrorLog メソッドによるログ取得
4. カスタムプロパティの追加と結果出力

**関連システム・外部連携**：SQL Server Agent の JobServer.ReadErrorLog メソッドを SMO 経由で実行。

**権限による制御**：SQL Server Agent のエラーログへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | Agentログ | 主機能 | SQLエージェントエラーログの取得 |

## 機能種別

データ取得 / トラブルシューティング / 監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| LogNumber | int[] | No | 取得するログファイル番号（0-9） | ValidateRange(0, 9) |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.ReadErrorLog メソッドから取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| LogDate | DateTime | ログエントリの作成日時 |
| ProcessInfo | String | プロセスIDまたはソースコンポーネント |
| Text | String | ログエントリのメッセージ内容 |

### 出力先

パイプライン出力として Microsoft.SqlServer.Management.Smo.LogFileEntry オブジェクトを返す。

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスに対してループ処理
   └─ Connect-DbaInstance で接続
   └─ 接続失敗時は Continue で次へ

2. ログ取得処理
   └─ LogNumber 指定時: 各番号でループ
   └─ LogNumber 未指定時: 全ログを取得

3. ReadErrorLog メソッド実行
   └─ LogNumber 指定: ReadErrorLog($number)
   └─ 未指定: ReadErrorLog()

4. 各ログエントリに対する処理
   └─ カスタムプロパティの追加
   └─ Select-DefaultView で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[インスタンス接続]
    C --> D{接続成功?}
    D -->|No| B
    D -->|Yes| E{LogNumber指定?}
    E -->|Yes| F[LogNumberループ]
    E -->|No| G[ReadErrorLog実行]
    F --> H[ReadErrorLog実行]
    G --> I[ログエントリループ]
    H --> I
    I --> J[カスタムプロパティ追加]
    J --> K[Select-DefaultView]
    K --> L[結果出力]
    L --> M{次のエントリ?}
    M -->|Yes| I
    M -->|No| N{次のLogNumber?}
    N -->|Yes| F
    N -->|No| O{次のインスタンス?}
    O -->|Yes| B
    O -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ログ番号範囲 | 0-9 の範囲でログファイルを指定 | LogNumber指定時 |
| BR-002 | 最新ログ | LogNumber 0 が最新のログ | 常時 |
| BR-003 | 全ログ取得 | LogNumber 未指定時は全ログを取得 | 未指定時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ログ取得 | SQLAGENT.OUT | READ | エラーログファイルの読み取り |

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

本機能は読み取り専用であり、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |
| ReadError | ログ読み取りエラー | ReadErrorLog 失敗 | Stop-Function で警告、Continue |

### リトライ仕様

特になし。

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

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

## パフォーマンス要件

- ログファイルサイズに依存
- 複数のログ番号を指定すると、各ログファイルが順次読み取られる
- 大量のログエントリがある場合、メモリ使用量が増加

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

- SQL Server Agent のエラーログへのアクセス権限が必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される
- ログにはセキュリティ関連の情報が含まれる可能性あり

## 備考

- LogNumber は 0（最新）から 9（最古）まで指定可能
- 古いログはサイクリングにより削除される場合あり
- Agent サービスの再起動時にログがローテーションされる

---

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

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

### 推奨読解順序

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

パラメータ定義と出力プロパティの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 74-83行目: パラメータ定義 |
| 1-2 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 39-55行目: .OUTPUTS ドキュメント |

**読解のコツ**: LogNumber の ValidateRange(0, 9) と、パイプライン入力対応に注目。

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

処理の起点となる process ブロックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 84-123行目: processブロック全体 |

**主要処理フロー**:
1. **85-90行目**: インスタンスへの接続
2. **92-107行目**: LogNumber 指定時の処理
3. **108-121行目**: LogNumber 未指定時の処理

#### Step 3: ログ読み取り処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 94-102行目: LogNumber指定時のReadErrorLog |
| 3-2 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 109-117行目: 全ログ取得のReadErrorLog |

**主要処理フロー**:
- **95行目**: `$server.JobServer.ReadErrorLog($number)` で指定番号のログ取得
- **110行目**: `$server.JobServer.ReadErrorLog()` で全ログ取得
- **97-99行目**: カスタムプロパティの追加
- **102行目**: Select-DefaultView で表示プロパティ設定

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

```
Get-DbaAgentLog
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           └─ [LogNumber]
                  │
                  ├─ [指定時] foreach ($number in $lognumber)
                  │      │
                  │      ├─ $server.JobServer.ReadErrorLog($number)
                  │      │
                  │      └─ foreach ($object in ...)
                  │             ├─ Add-Member (ComputerName, InstanceName, SqlInstance)
                  │             └─ Select-DefaultView
                  │
                  └─ [未指定]
                         │
                         ├─ $server.JobServer.ReadErrorLog()
                         │
                         └─ foreach ($object in ...)
                                ├─ Add-Member (ComputerName, InstanceName, SqlInstance)
                                └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
LogNumber ───────────────────▶ $server.JobServer.ReadErrorLog
(0-9)                           │
                                ▼
                          LogFileEntry[]
                                │
                                ▼
                          Add-Member
                          - ComputerName
                          - InstanceName
                          - SqlInstance
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ LogFileEntry Objects
                                                                    - LogDate
                                                                    - ProcessInfo
                                                                    - Text
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaErrorLog.ps1 | `public/Get-DbaErrorLog.ps1` | ソース | 関連機能（SQL Serverエラーログ） |
