# 機能設計書 46-ログ管理

## 概要

本ドキュメントは、Laravel Frameworkのログ管理機能の設計仕様を定義する。LogManagerクラスを中心とした、ログの記録・管理・チャンネル制御について詳述する。

### 本機能の処理概要

ログ管理は、アプリケーションの動作記録、エラー追跡、デバッグ情報の出力を一元的に管理する機能を提供する。Monologをベースとし、複数のログチャンネル（ファイル、Slack、Syslog等）への出力、スタックによる複数チャンネルへの同時出力、チャンネル間での共有コンテキストなどをサポートする。

**業務上の目的・背景**：運用中のアプリケーションでは、障害調査、監査、パフォーマンス分析のためにログが不可欠である。適切なログ管理により、問題の早期発見、原因特定の効率化、システム動作の可視化が実現する。また、PSR-3準拠のインターフェースにより、他のライブラリとの互換性も確保される。

**機能の利用シーン**：エラーログの記録、デバッグ情報の出力、監査ログの記録、パフォーマンス計測、外部サービス連携通知（Slack等）などで利用される。

**主要な処理内容**：
1. ログチャンネルの管理（single、daily、stack、slack、syslog等）
2. ログレベルの制御（emergency、alert、critical、error、warning、notice、info、debug）
3. 共有コンテキストの管理
4. カスタムドライバの登録
5. オンデマンドログチャンネルの構築

**関連システム・外部連携**：Monolog、Slack Webhook、Syslog、各種外部ロギングサービスと連携する。

**権限による制御**：ログ管理自体には権限制御は存在しないが、ログファイルへのアクセス権限はOSレベルで制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングにログ管理関連の画面なし |

## 機能種別

ログ記録 / 監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| message | string\|Stringable | Yes | ログメッセージ | - |
| context | array | No | コンテキストデータ | - |
| level | string | Yes | ログレベル | PSR-3ログレベル |
| channel | string\|null | No | ログチャンネル名 | 設定済みチャンネル名 |

### 入力データソース

- アプリケーションコードからのログ出力
- 例外ハンドラからの自動ログ出力
- フレームワーク内部からのログ出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| log entry | void | ログ出力（戻り値なし） |

### 出力先

- ログファイル（storage/logs/）
- Syslog
- Slack Webhook
- 標準エラー出力（errorlog）
- カスタムハンドラ

## 処理フロー

### 処理シーケンス

```
1. ログ出力リクエスト
   └─ info()、error()等のメソッド呼び出し

2. ドライバ解決
   └─ driver()でチャンネル名からロガーインスタンス取得
   └─ 未解決の場合はresolve()で新規作成

3. ロガー作成
   └─ create{Driver}Driverメソッドで対応ハンドラ作成
   └─ Loggerでラップして返却

4. コンテキスト付与
   └─ 共有コンテキストを自動追加

5. ログ出力
   └─ Monologハンドラにログを出力
```

### フローチャート

```mermaid
flowchart TD
    A[ログメソッド呼び出し] --> B[driver 解決]
    B --> C{キャッシュ済み?}
    C -->|Yes| D[キャッシュから取得]
    C -->|No| E[resolve で作成]
    E --> F{設定存在?}
    F -->|No| G[InvalidArgumentException]
    F -->|Yes| H{カスタムドライバ?}
    H -->|Yes| I[callCustomCreator]
    H -->|No| J{ドライバタイプ}
    J -->|single| K[createSingleDriver]
    J -->|daily| L[createDailyDriver]
    J -->|slack| M[createSlackDriver]
    J -->|syslog| N[createSyslogDriver]
    J -->|stack| O[createStackDriver]
    K --> P[Logger作成]
    L --> P
    M --> P
    N --> P
    O --> P
    I --> P
    D --> Q[withContext で共有コンテキスト追加]
    P --> Q
    Q --> R[Monolog出力]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-1 | 緊急ロガー | ロガー作成失敗時は緊急ロガーを使用 | resolve()内で例外発生時 |
| BR-46-2 | スタックログ | stackドライバは複数チャンネルにログ出力 | config.driver が stack |
| BR-46-3 | 共有コンテキスト | shareContext()で登録されたコンテキストは全チャンネルに追加 | shareContext()呼び出し後 |
| BR-46-4 | ユニットテスト時null | ユニットテスト実行時はnullドライバがデフォルト | runningUnitTests() が true |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | ログ管理自体はデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgumentException | ログ未定義 | 指定されたログチャンネルが設定されていない | config/logging.phpにチャンネルを追加 |
| InvalidArgumentException | ドライバ未サポート | 指定されたドライバがサポートされていない | サポートされているドライバを使用 |

### リトライ仕様

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

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

ログ管理はトランザクション管理を行わない。

## パフォーマンス要件

- ログ出力は同期的に行われるため、高頻度のログ出力はパフォーマンスに影響
- ローテーションログ（daily）は日次でファイルを分割

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

- センシティブ情報（パスワード、トークン等）をログに出力しないよう注意
- ログファイルのアクセス権限を適切に設定
- Slackへの出力時はWebhook URLを安全に管理

## 備考

- PSR-3 LoggerInterface準拠
- Monolog 3.x系を使用

---

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

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

### 推奨読解順序

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

LogManagerが管理する内部状態を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | LogManager.php | `src/Illuminate/Log/LogManager.php` | プロパティ定義（38-66行目）で管理される状態を把握 |
| 1-2 | LoggerInterface | PSR-3 | PSR-3インターフェース定義 |

**読解のコツ**: $channelsで解決済みチャンネルをキャッシュ、$sharedContextで共有コンテキストを管理、$customCreatorsでカスタムドライバを登録。

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

ログ出力の入口を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | LogManager.php | `src/Illuminate/Log/LogManager.php` | info()、error()等（741-770行目）がログ出力エントリー |
| 2-2 | LogManager.php | `src/Illuminate/Log/LogManager.php` | driver()（123-126行目）でチャンネル取得 |

**主要処理フロー**:
1. **741-744行目**: info()はdriver()->info()を呼び出し
2. **123-126行目**: driver()はget()を呼び出してロガー取得
3. **135-157行目**: get()でキャッシュまたはresolve()で新規作成

#### Step 3: チャンネル解決処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | LogManager.php | `src/Illuminate/Log/LogManager.php` | resolve()（217-236行目） |
| 3-2 | LogManager.php | `src/Illuminate/Log/LogManager.php` | configurationFor()（563-566行目） |

**主要処理フロー**:
- **219-223行目**: 設定がなければInvalidArgumentException
- **225-226行目**: カスタムドライバがあればそれを使用
- **229-233行目**: 標準ドライバはcreate{Driver}Driverメソッドで作成

#### Step 4: 各ドライバの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | LogManager.php | `src/Illuminate/Log/LogManager.php` | createSingleDriver()（303-313行目） |
| 4-2 | LogManager.php | `src/Illuminate/Log/LogManager.php` | createDailyDriver()（321-329行目） |
| 4-3 | LogManager.php | `src/Illuminate/Log/LogManager.php` | createSlackDriver()（337-353行目） |
| 4-4 | LogManager.php | `src/Illuminate/Log/LogManager.php` | createStackDriver()（268-295行目） |

**主要処理フロー**:
- **305-311行目**: SingleはStreamHandlerでファイル出力
- **323-327行目**: DailyはRotatingFileHandlerで日次ローテーション
- **339-351行目**: SlackはSlackWebhookHandlerでWebhook送信
- **274-280行目**: Stackは複数チャンネルのハンドラを集約

#### Step 5: 共有コンテキストを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | LogManager.php | `src/Illuminate/Log/LogManager.php` | shareContext()（497-506行目） |
| 5-2 | LogManager.php | `src/Illuminate/Log/LogManager.php` | sharedContext()（513-516行目） |
| 5-3 | LogManager.php | `src/Illuminate/Log/LogManager.php` | withoutContext()（524-533行目） |

**主要処理フロー**:
- **499-501行目**: 既存チャンネルにコンテキストを追加
- **503行目**: $sharedContextにマージして保存
- **524-533行目**: コンテキストのクリア

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

```
Log::info($message, $context) [ファサード]
    │
    └─ LogManager::info($message, $context)
           │
           └─ LogManager::driver()
                  │
                  └─ LogManager::get($name)
                         │
                         ├─ [キャッシュあり] $channels[$name]
                         │
                         └─ [キャッシュなし]
                            LogManager::resolve($name)
                                │
                                ├─ configurationFor($name)
                                │
                                ├─ [カスタム] callCustomCreator($config)
                                │
                                └─ [標準] create{Driver}Driver($config)
                                       │
                                       ├─ createSingleDriver()
                                       │      └─ new StreamHandler()
                                       │
                                       ├─ createDailyDriver()
                                       │      └─ new RotatingFileHandler()
                                       │
                                       └─ createStackDriver()
                                              └─ 各チャンネルのhandlersを集約
```

### データフロー図

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

$message, $context ───▶  driver()->info()        ───▶  Loggerインスタンス
(ログデータ)              (チャンネル取得)

$config           ───▶  create*Driver()          ───▶  Monolog Logger
(チャンネル設定)          (ドライバ作成)

$sharedContext    ───▶  withContext()            ───▶  コンテキスト追加済みLogger
(共有コンテキスト)        (コンテキスト付与)

Logger + message  ───▶  Monolog::log()           ───▶  ログファイル/Slack/Syslog
(ログ出力)               (出力実行)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| LogManager.php | `src/Illuminate/Log/LogManager.php` | ソース | ログ管理のメイン実装 |
| Logger.php | `src/Illuminate/Log/Logger.php` | ソース | Monologラッパー |
| LogServiceProvider.php | `src/Illuminate/Log/LogServiceProvider.php` | ソース | サービスプロバイダ |
| ParsesLogConfiguration.php | `src/Illuminate/Log/ParsesLogConfiguration.php` | ソース | 設定解析トレイト |
| Context/Repository.php | `src/Illuminate/Log/Context/Repository.php` | ソース | コンテキストリポジトリ |
