# 画面設計書 17-Agentログ

## 概要

本ドキュメントは、SQL Server Agent エラーログの取得機能を提供するコマンドの設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server Agent のエラーログエントリを取得し、Agent サービスのアクティビティ、ジョブ失敗、システムイベントの詳細情報を提供します。

**業務上の目的・背景**：SQL Server Agent のログを確認することで、ジョブ失敗のトラブルシューティング、Agent サービスの健全性監視、自動化プロセスのコンプライアンス監査が可能です。SSMS でログを手動確認する代わりに、PowerShell で効率的にログを取得・分析できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentLog` - Agent エラーログの取得

**主要な操作・処理内容**：
1. SQL Server Agent のエラーログエントリを取得
2. 複数のログファイル（0-9）から履歴ログを取得
3. 複数インスタンスから一括でログを取得

**画面遷移**：本機能はCLIコマンドです。

**権限による表示制御**：SQL Agent エラーログへの読み取り権限が必要です。

## 関連機能

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

## 画面種別

一覧

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）

## 入出力項目

### Get-DbaAgentLog パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| LogNumber | int[] | No | ログファイル番号（0-9）、0が最新 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentLog 出力

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

## イベント仕様

### 1-Agentログ取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. `-LogNumber` 指定時は各ログ番号に対して `$server.JobServer.ReadErrorLog($number)` を実行
3. `-LogNumber` 未指定時は `$server.JobServer.ReadErrorLog()` で現在のログを取得
4. 各ログエントリに ComputerName/InstanceName/SqlInstance を追加
5. `Select-DefaultView` で整形して出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentLog | ファイルシステム | READ | Agentエラーログファイルの読み取り |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | 接続失敗 | "Failure" (ConnectionError) |
| Error | ログ読み取り失敗 | "Could not read from SQL Server Agent" |

## 備考

- ログ番号は 0-9 の範囲（ValidateRange で検証）
- ログ 0 は最新のエントリを含み、番号が大きくなるほど古いログ
- 複数のログ番号を指定した場合、すべてのエントリが返される

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 39-56行: .OUTPUTS セクションでLogFileEntryオブジェクト構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 74-83行: パラメータ定義 |
| 2-2 | Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | 80-81行: LogNumberのValidateRange(0,9) |

**主要処理フロー**:
- **92-107行**: LogNumber指定時のループ処理
- **95行**: `$server.JobServer.ReadErrorLog($number)` でログ読み取り
- **108-122行**: LogNumber未指定時の現在ログ取得

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

```
Get-DbaAgentLog
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- [LogNumber指定時]
    |       +-- foreach ($number in $lognumber)
    |           +-- $server.JobServer.ReadErrorLog($number)
    |
    +-- [LogNumber未指定時]
    |       +-- $server.JobServer.ReadErrorLog()
    |
    +-- Add-Member (カスタムプロパティ追加)
    |
    +-- Select-DefaultView (出力整形)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentLog.ps1 | `public/Get-DbaAgentLog.ps1` | ソース | Agentログ取得のメインコマンド |
