# 画面設計書 274-ログ取得

## 概要

本ドキュメントは、dbatoolsモジュールのログ取得機能（Get-DbatoolsLog）に関する画面設計書です。

### 本画面の処理概要

dbatoolsモジュールの内部ログエントリを取得し、コマンド実行のトラブルシューティングやデバッグを支援するPowerShellコマンドを提供します。

**業務上の目的・背景**：SQL Server管理業務において、dbatoolsコマンドの実行結果が期待通りでない場合や、接続エラーが発生した場合のトラブルシューティングが必要です。本機能により、詳細な実行ログを取得し、問題の原因特定を効率的に行うことができます。また、自動化スクリプトの動作確認やデバッグにも活用できます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから`Get-DbatoolsLog`コマンドを実行します。

**主要な操作・処理内容**：
1. メモリ内のログエントリ全体の取得
2. 関数名、モジュール名、ターゲットによるフィルタリング
3. タグベースのフィルタリング
4. 直近N回の実行履歴に限定した取得
5. 最後のエラーのみの取得
6. メッセージレベルによるフィルタリング

**画面遷移**：CLIベースのため画面遷移は存在しません。

**権限による表示制御**：特別な権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 158 | Get-DbatoolsLog | 主機能 | dbatoolsログの取得 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンドレット
- `Get-DbatoolsLog`

## 入出力項目

### Get-DbatoolsLog

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| FunctionName | string | No | 関数名でフィルター（ワイルドカード対応、デフォルト: "*"） |
| ModuleName | string | No | モジュール名でフィルター（ワイルドカード対応、デフォルト: "*"） |
| Target | object | No | ターゲットオブジェクトでフィルター |
| Tag | string[] | No | タグでフィルター |
| Last | int | No | 直近N回の実行からログを取得 |
| LastError | switch | No | 最後のエラーのみを取得 |
| Skip | int | No | 直近N回をスキップ（デフォルト: 0） |
| Runspace | guid | No | Runspace GUIDでフィルター |
| Level | MessageLevel[] | No | メッセージレベルでフィルター |
| Raw | switch | No | 生のLogEntryオブジェクトを返す |
| Errors | switch | No | エラーエントリのみを取得 |

## 表示項目

### Get-DbatoolsLog出力（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CallStack | string | ログ生成時のコールスタック |
| ComputerName | string | コンピュータ名 |
| File | string | スクリプトファイル名 |
| FunctionName | string | 関数名 |
| Level | MessageLevel | メッセージレベル（Critical, Error, Warning, Info, Verbose等） |
| Line | int | 行番号 |
| Message | string | ログメッセージ（複数行は単一行に結合） |
| ModuleName | string | モジュール名 |
| Runspace | guid | Runspace GUID |
| Tags | string[] | タグ配列 |
| TargetObject | object | 処理対象オブジェクト |
| Timestamp | datetime | タイムスタンプ |
| Type | string | ログエントリタイプ |
| Username | string | 実行ユーザー名 |

### Get-DbatoolsLog出力（-Raw指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （戻り値） | LogEntry | 生のLogEntryオブジェクト（複数行メッセージ保持） |

## イベント仕様

### 1-ログ取得

Get-DbatoolsLogコマンド実行時、LogHostクラスからログまたはエラーエントリを取得し、指定されたフィルター条件で絞り込みます。

**処理詳細**：
1. Errorsパラメータの確認
   - 指定あり：LogHost.GetErrors()を呼び出し
   - 指定なし：LogHost.GetLog()を呼び出し
2. FunctionName、ModuleNameでフィルタリング
3. LastErrorパラメータ指定時は最後のエラーのみ取得
4. Target、Tag、Runspace、Levelでの追加フィルタリング
5. Lastパラメータ指定時はGet-Historyから該当期間を特定
6. Rawでなければメッセージの複数行を単一行に変換して出力

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

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

本機能はSQL Serverデータベースに対する直接的な操作は行いません。dbatoolsモジュールの内部ログを参照するのみです。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | SELECT（メモリ内） | ログエントリの読み取りのみ |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| （なし） | 本コマンドは特別なメッセージを出力しません | - |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Lastパラメータ指定時に履歴が不足 | エラーは発生せず、利用可能な履歴範囲で処理 |

## 備考

- LogHostクラスは.NET側で実装されており、静的メソッドでログを管理
- Get-DbatoolsLog自身の実行履歴はLast計算から除外される
- MessageLevelにはCritical, Error, Warning, Info, Verbose, Debug等が存在
- 複数行メッセージは空白で結合され、連続空白は単一空白に置換される（Rawでない場合）
- Runspaceフィルタはマルチスレッド/バックグラウンド処理のデバッグに有用

---

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

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

### 推奨読解順序

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

ログエントリはLogHostクラスで管理され、各エントリはLogEntry型として表現されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 出力されるログエントリの構造を理解（65-88行目） |

**読解のコツ**: LogHostクラスの静的メソッドGetLog()とGetErrors()がログの取得元です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ログ取得のメインロジック |

**主要処理フロー**:
1. **126-134行目**: Errorsパラメータによる分岐（GetErrors() vs GetLog()）
2. **136-138行目**: LastErrorパラメータの処理
3. **140-142行目**: Targetによるフィルタリング
4. **144-150行目**: Tagによるフィルタリング
5. **152-154行目**: Runspaceによるフィルタリング
6. **156-164行目**: Lastパラメータによる履歴ベースのフィルタリング
7. **166-168行目**: Levelによるフィルタリング
8. **170-183行目**: 出力形式の決定（Raw vs 整形済み）

#### Step 3: メッセージ整形を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | メッセージの複数行→単一行変換（173-182行目） |

**主要処理フロー**:
- **176行目**: 改行で分割して空白で結合
- **177-179行目**: 連続空白を単一空白に置換

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

```
Get-DbatoolsLog
    │
    ├─ [Dataplat.Dbatools.Message.LogHost]::GetLog()
    │      └─ Where-Object (FunctionName, ModuleName)
    │             └─ Where-Object (Target, Tag, Runspace, Level)
    │
    ├─ [Dataplat.Dbatools.Message.LogHost]::GetErrors()
    │      └─ Where-Object (フィルタリング)
    │
    ├─ Get-History
    │      └─ 履歴から期間を特定（Lastパラメータ用）
    │
    └─ Select-Object
           └─ プロパティ選択とメッセージ整形
```

### データフロー図

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

フィルターパラメータ ──▶ LogHost.GetLog() ─────────────────▶ LogEntry[]
                              │
                              ├─ Where-Object (条件フィルタ)
                              │
                              └─ Select-Object (プロパティ選択)
                                     │
                    Raw ─────────────┼─▶ 生のLogEntry
                                     │
                    !Raw ────────────┼─▶ 整形済みPSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | ログ取得コマンド |
| Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | ソース | エラー取得（関連機能） |
