# 機能設計書 158-Get-DbatoolsLog

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbatoolsLog` コマンドレットの機能設計を記述する。本機能は、dbatoolsモジュール実行中の内部ログエントリとエラーメッセージを取得するための機能である。

### 本機能の処理概要

dbatoolsの内部ロギングシステムからログエントリを取得し、コマンド実行のトレースやデバッグに必要な詳細情報を提供する機能である。

**業務上の目的・背景**：dbatoolsコマンドが期待どおりに動作しない場合、内部で何が起きているかを把握する必要がある。内部ロギングシステムは、各コマンドの実行状況、処理ステップ、警告、エラーを記録している。本機能は、これらのログを取得し、特定の関数、モジュール、ターゲット、タグでフィルタリングすることで、効率的なトラブルシューティングを可能にする。

**機能の利用シーン**：
- コマンド実行時の詳細ログ確認
- 特定の関数（例: Backup-DbaDatabase）のログ抽出
- エラー発生時の詳細調査
- 直近N回のコマンド実行ログ取得
- 特定のターゲット（サーバー、データベース）に関するログ抽出

**主要な処理内容**：
1. 内部ロギングシステム（LogHost）からログエントリを取得
2. 関数名、モジュール名、ターゲット、タグ、レベルによるフィルタリング
3. 実行履歴に基づく時間範囲フィルタリング
4. マルチラインメッセージのフラット化（オプション）

**関連システム・外部連携**：dbatools内部ロギングシステム（Dataplat.Dbatools.Message.LogHost）

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

## 関連画面

本機能はコマンドライン機能であり、直接的な関連画面は存在しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

診断・トラブルシューティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FunctionName | string | No | 関数名でフィルタ（ワイルドカード対応）。デフォルト: "*" | - |
| ModuleName | string | No | モジュール名でフィルタ（ワイルドカード対応）。デフォルト: "*" | - |
| Target | object | No | ターゲットオブジェクトでフィルタ | AllowNull |
| Tag | string[] | No | タグ配列でフィルタ | - |
| Last | int | No | 直近N回のコマンド実行のログを取得 | 正の整数 |
| LastError | switch | No | 最後のエラーのみ取得 | - |
| Skip | int | No | 直近からスキップする実行数。デフォルト: 0 | 0以上の整数 |
| Runspace | guid | No | 特定のRunspace IDでフィルタ | 有効なGUID |
| Level | MessageLevel[] | No | ログレベルでフィルタ（Critical, Error, Warning等） | - |
| Raw | switch | No | 生のLogEntryオブジェクトを返す | - |
| Errors | switch | No | エラーエントリのみ取得 | - |

### 入力データソース

- ユーザー入力（コマンドラインパラメータ）
- 内部ロギングシステム（LogHost.GetLog(), LogHost.GetErrors()）
- コマンド履歴（Get-History）

## 出力仕様

### 出力データ（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CallStack | string | ログ作成時のコールスタック |
| ComputerName | string | ログ生成コンピュータ名 |
| File | string | ログ発生元のスクリプトファイル名 |
| FunctionName | string | ログを作成した関数名 |
| Level | MessageLevel | ログレベル（Critical, Error, Warning, Info, Verbose等） |
| Line | int | スクリプトファイル内の行番号 |
| Message | string | ログメッセージ（マルチライン圧縮済み） |
| ModuleName | string | モジュール名 |
| Runspace | guid | PowerShell Runspace ID |
| Tags | string[] | ログに関連付けられたタグ |
| TargetObject | object | 処理対象オブジェクト |
| Timestamp | DateTime | ログ作成日時 |
| Type | string | ログエントリタイプ |
| Username | string | コマンド実行ユーザー |

### 出力データ（Raw指定時）

Dataplat.Dbatools.Message.LogEntry オブジェクトをそのまま出力

### 出力先

- PowerShellパイプライン
- コンソール出力

## 処理フロー

### 処理シーケンス

```
1. ログソース選択
   ├─ Errors指定 → LogHost.GetErrors()
   └─ 通常 → LogHost.GetLog()

2. 関数名/モジュール名フィルタ
   └─ FunctionName, ModuleName パターンマッチ

3. LastError処理
   └─ 指定時は最後のエラーエントリのみ取得

4. 追加フィルタ適用
   ├─ Target指定 → TargetObjectで等価比較
   ├─ Tag指定 → Tags配列内で一致チェック
   ├─ Runspace指定 → Runspace GUIDで比較
   └─ Level指定 → Levelで一致チェック

5. Last/Skip処理
   └─ 履歴から時間範囲を計算し、その範囲のログを取得

6. 出力形式選択
   ├─ Raw指定 → LogEntryをそのまま出力
   └─ 通常 → Messageをフラット化してPSCustomObject出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Errors指定?}
    B -->|Yes| C[LogHost.GetErrors]
    B -->|No| D[LogHost.GetLog]
    C --> E[FunctionName/ModuleNameフィルタ]
    D --> E
    E --> F{LastError指定?}
    F -->|Yes| G[最後のエラーのみ]
    F -->|No| H{Target指定?}
    G --> H
    H -->|Yes| I[Targetフィルタ]
    H -->|No| J{Tag指定?}
    I --> J
    J -->|Yes| K[Tagフィルタ]
    J -->|No| L{Runspace指定?}
    K --> L
    L -->|Yes| M[Runspaceフィルタ]
    L -->|No| N{Last指定?}
    M --> N
    N -->|Yes| O[履歴から時間範囲計算]
    N -->|No| P{Level指定?}
    O --> P
    P -->|Yes| Q[Levelフィルタ]
    P -->|No| R{Raw指定?}
    Q --> R
    R -->|Yes| S[LogEntry出力]
    R -->|No| T[Message圧縮&PSCustomObject出力]
    S --> U[終了]
    T --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトワイルドカード | FunctionName, ModuleNameのデフォルトは"*" | パラメータ未指定時 |
| BR-002 | Get-DbatoolsLog除外 | Last指定時、自身の呼び出しは履歴から除外 | Last指定時 |
| BR-003 | マルチラインフラット化 | デフォルトでは改行を空白に変換し連続空白を圧縮 | Raw未指定時 |
| BR-004 | DefaultRunspaceフィルタ | Last指定時は現在のRunspaceのログのみ | Last指定時 |

### 計算ロジック

- **マルチラインフラット化**: `($_.Message.Split("`n") -join " ")` で改行を空白に変換、その後連続空白を単一空白に圧縮

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

本機能はデータベースにアクセスしない。

## エラー処理

### エラーケース一覧

本機能自体はエラーを発生させない。ログが存在しない場合は空結果を返す。

### リトライ仕様

リトライは実装されていない。

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

本機能は読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- ログはメモリ上に保持されており、即時取得可能
- 大量のログが存在する場合でも数ミリ秒で完了
- フィルタリングは順次適用されるため、早期に絞り込むと効率的

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

- ログにはセンシティブな情報（SQL文、接続情報等）が含まれる可能性がある
- ログファイルや画面共有時は注意が必要

## 備考

- 関連コマンド: Get-DbatoolsError
- Rawパラメータ使用でSQL文などの複数行メッセージを元の形式で取得可能

---

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

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

### 推奨読解順序

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

本機能は2種類の出力形式を持つ。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 64-88行目の.OUTPUTSセクションで出力構造を確認 |

**読解のコツ**: Raw指定時とデフォルト時の出力の違いを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 110-124行目のパラメータ定義 |

**主要処理フロー**:
1. **110-124行目**: パラメータ定義（多数のフィルタオプション）
2. **125-184行目**: processブロックのメイン処理

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 126-134行目のログ取得 |
| 3-2 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 136-168行目のフィルタリング |
| 3-3 | Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | 170-183行目の出力処理 |

**主要処理フロー**:
- **126-134行目**: Errors/通常でのログソース選択とFunctionName/ModuleNameフィルタ
- **136-138行目**: LastError処理
- **140-150行目**: Target, Tag, Runspaceフィルタ
- **156-164行目**: Last指定時の履歴ベースフィルタ
- **166-168行目**: Levelフィルタ
- **170-183行目**: Raw/通常での出力形式選択

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

```
Get-DbatoolsLog
    │
    ├─ LogHost.GetLog() / LogHost.GetErrors()
    │      └─ ログエントリ取得
    │
    ├─ Where-Object (複数回)
    │      ├─ FunctionName/ModuleName フィルタ
    │      ├─ Target フィルタ
    │      ├─ Tag フィルタ
    │      ├─ Runspace フィルタ
    │      ├─ Last 時間範囲フィルタ
    │      └─ Level フィルタ
    │
    ├─ Get-History
    │      └─ Last指定時の時間範囲計算
    │
    └─ Select-Object
           └─ プロパティ選択とMessage圧縮
```

### データフロー図

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

Errors ────────▶ ログソース選択
                       │
FunctionName ──────────┤
ModuleName ────────────┤
                       ▼
                 FunctionName/ModuleName フィルタ
                       │
Target ────────────────┤
Tag ───────────────────┤
Runspace ──────────────┤
                       ▼
                 追加フィルタ適用
                       │
Last ──────────────────┤
Skip ──────────────────┤
                       ▼
                 履歴ベース時間範囲フィルタ
                       │
Level ─────────────────┤
                       ▼
                 Levelフィルタ
                       │
Raw ───────────────────┤
                       ▼
            ┌──────────┴──────────┐
         Raw=Yes              Raw=No
            │                    │
            ▼                    ▼
       LogEntry             PSCustomObject
       (生データ)           (Message圧縮済み)
            │                    │
            └──────────┬─────────┘
                       ▼
                パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | メイン機能実装 |
| Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | ソース | エラー取得（関連コマンド） |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータバインドチェック |
