# B35_統一ロギングシステムガイド

## 概要

本システムは統一されたロギング機能を提供し、全モジュールで一貫したログ出力を実現します。

## 基本使用方法

### 統一ロガーの取得

```python
from noveler.infrastructure.logging.unified_logger import get_logger

logger = get_logger(__name__)
logger.info("処理開始")
logger.debug("デバッグ情報", extra={"data": some_data})
```

### 従来の方法（禁止）

```python
# ❌ 禁止: レガシーロギング
import logging
logger = logging.getLogger(__name__)
```

## 機能

### 1. Rich形式出力（人間向け）

```python
from noveler.infrastructure.logging.unified_logger import configure_logging, LogFormat

# Rich形式に切り替え
configure_logging(console_format=LogFormat.RICH)
```

### 2. JSON形式出力（機械向け）

```python
# JSON形式に切り替え
configure_logging(console_format=LogFormat.JSON)
```

### 3. 動的ログレベル制御

```python
from noveler.infrastructure.logging.unified_logger import LogLevel

# DEBUGレベルに切り替え
configure_logging(verbose=2)

# 特定レベルに設定
configure_logging(console_level=LogLevel.WARNING)
```

### 4. ファイル出力

- 自動ローテーション（最大10MB、5世代保持）
- JSON形式でのファイル出力
- UTF-8エンコーディング
- JSONログは `schema_version` と `environment` を含み、`NOVEL_LOG_SCHEMA_VERSION` で任意に上書き可能

## ベストプラクティス

### 1. ロガー名の統一

```python
# ✅ 推奨: __name__ を使用
logger = get_logger(__name__)

# ❌ 非推奨: ハードコードされた名前
logger = get_logger("my_module")
```

### 2. 適切なログレベル

```python
# 情報出力
logger.info("ユーザーアクション実行")

# デバッグ情報
logger.debug("内部状態確認", extra={"state": current_state})

# 警告
logger.warning("設定ファイルが見つかりません")

# エラー
logger.error("処理に失敗", exc_info=True)

# クリティカル
logger.critical("システム停止")
```

### 3. 構造化ログ

```python
# ✅ 推奨: 構造化されたログ
logger.info(
    "ユーザー認証成功",
    extra={
        "user_id": user.id,
        "session_id": session.id,
        "timestamp": datetime.now().isoformat()
    }
)

# ❌ 非推奨: 文字列結合
logger.info(f"ユーザー {user.id} が認証に成功しました")
```

### 4. エラーハンドリングとの統合

```python
try:
    risky_operation()
except Exception as e:
    logger.error(
        "操作に失敗",
        extra={
            "operation": "risky_operation",
            "error_type": type(e).__name__,
            "error_message": str(e)
        },
        exc_info=True
    )
    raise
```

## パフォーマンス考慮事項

### 1. ログレベル最適化

```python
from noveler.infrastructure.logging.unified_logger import LogLevel

# ✅ 推奨: デバッグ情報は条件付き
if logger.isEnabledFor(LogLevel.DEBUG.value):
    logger.debug("重い処理結果", extra={"result": expensive_operation()})

# ❌ 非推奨: 常に重い処理を実行
logger.debug("重い処理結果", extra={"result": expensive_operation()})
```

### 2. シングルトンパターンの活用

統一ロガーはシングルトンパターンを採用しており、メモリ効率的です。

```python
# 複数回呼び出しても同じインスタンス
logger1 = get_logger(__name__)
logger2 = get_logger(__name__)
assert logger1 is logger2  # True
```

## 環境別プリセット

> 例: `from noveler.infrastructure.logging.unified_logger import LogFormat, LogLevel, configure_logging`

### 開発環境 (Dev)

- 推奨呼び出し: `configure_logging(console_format=LogFormat.RICH, verbose=1)`
- `NOVEL_LOG_LEVEL=DEBUG` を指定すると CLI なしでも詳細ログを取得可能

### 本番環境 (Prod)

- 推奨呼び出し: `configure_logging(console_format=LogFormat.JSON, console_level=LogLevel.WARNING, quiet=True)`
- `NOVEL_PRODUCTION_MODE=1` を設定するとファイル出力が JSON 固定になり、機械処理しやすくなる

### MCP統合環境

- `MCP_STDIO_SAFE=1` または `configure_logging(preset="mcp")` で stderr 出力を完全に停止し、MCP の JSON-RPC 通信を汚染しない
- CLI ツール側では `configure_logging(preset="mcp")` を呼び出し、JSON ログのみを書き出す運用を推奨
- `NOVEL_LOG_DIR` / `NOVEL_LOG_FILE` を併用するとサーバー側でログファイル出力先を固定できる

## Domain層ポリシー (B30/B35)

- Domain 層では `import logging` を禁止し、`NullLoggerService`/`NullLogger` を既定として使用する
- 実運用では Application 層が `ILoggerService` を注入し、統一ロガーへブリッジする
- ML 類似度サービスなどロガー注入が必要なケースは `noveler.infrastructure.factories.ml_similarity_service_factory.create_ml_similarity_service()` で `get_logger(__name__)` を既定注入する
- Console 出力は `noveler.domain.utils.domain_console.get_console()` を経由し、UI/Presentation への静的依存を避ける
- Domain からのメッセージは `noveler.domain.utils.domain_logging.capture_domain_logs()` で捕捉でき、MCP 応答などに構造化して返却する（UI出力は必要に応じて抑制可）
- パス解決は `get_path_service_manager()` を用いて取得し、`shared_utilities` へ直接依存しない
- `rich` や Presentation 層のユーティリティを Domain から参照しない (品質ゲートでブロック)

## CLIオプション統合

### 1. 基本オプション

```bash
# 詳細モード
python script.py --verbose

# さらに詳細モード
python script.py -vv

# 静寂モード
python script.py --quiet

# JSON出力
python script.py --log-format json
```

### 2. 環境変数制御

```bash
# ログレベル設定
export NOVEL_LOG_LEVEL=DEBUG
python script.py
```

## 開発ツール

### 1. 移行ツール

```bash
# レポート生成
python src/noveler/infrastructure/tools/logging_migration_tool.py --report-only

# レイヤー別移行
python src/noveler/infrastructure/tools/logging_migration_tool.py --layer infrastructure --execute
```

### 2. 品質ゲート

```bash
# 品質チェック
python src/noveler/infrastructure/quality_gates/unified_logging_gate.py --project-root .

# 修正提案表示
python src/noveler/infrastructure/quality_gates/unified_logging_gate.py --project-root . --suggest-fixes
```

#### 品質ゲートで除外しているパス

統一ロギング品質ゲートは「本番コード」に限定して違反を検知します。次のパスは運用上の理由で除外されています。

- `scripts/`: 運用スクリプト群。CLIユーティリティや移行ツールは段階的に統一ロガーへ移行中のため警告対象外としています。
- `tests/`: テストコードでは標準ライブラリの`logging`を使ったフィクスチャや相互運用確認が残っているため、品質ゲートの対象外です。
- `src/noveler/tools/`: ドキュメント生成やレポート用途の補助ツール。テスト同様に標準ロギングの利用を暫定容認しています。
- `src/noveler/infrastructure/logging/`: 統一ロギング基盤そのものを実装する層であり、標準`logging`モジュールとの橋渡しが必須のため除外します。

上記以外の本番コードで `import logging` や `logging.getLogger` が検出された場合は品質ゲートが失敗し、統一ロガーへ移行する必要があります。

### 3. Pre-commitフック

```bash
# フック設定（pre-commit 利用時は自動実行）
python src/noveler/infrastructure/git/hooks/unified_logging_pre_commit.py

# .pre-commit-config.yaml に統一ロギング品質ゲートが登録済み
pre-commit install
```

## トラブルシューティング

### 1. ログが表示されない

- ログレベルが適切に設定されているか確認
- `--quiet` オプションが指定されていないか確認
- 環境変数 `NOVEL_LOG_LEVEL` を確認

### 2. パフォーマンス問題

- 不要なDEBUGログが有効になっていないか確認
- 重い処理を含むログ出力の条件分岐を追加
- ファイルローテーションの設定を調整

### 3. 移行エラー

```bash
# 移行状況確認
python src/noveler/infrastructure/tools/logging_migration_tool.py --report-only

# 品質チェック
python src/noveler/infrastructure/quality_gates/unified_logging_gate.py --project-root . --warn-only
```

## 設計思想

### 1. DDD層構造との整合

- Infrastructure層: 統一ロガー実装
- Application層: ユースケースでの利用
- Domain層: 限定的な利用（実用性重視）
- ML 類似度サービスなどロガー注入が必要なケースは `noveler.infrastructure.factories.ml_similarity_service_factory.create_ml_similarity_service()` を利用し、`get_logger(__name__)` に統一する

### 2. エンタープライズ品質

- ローテーション機能
- 複数出力形式対応
- 動的設定変更
- パフォーマンス最適化

### 3. 開発者体験

- 簡単なAPI
- 自動移行ツール
- 品質ゲート統合
- Pre-commitフック

## 更新履歴

- 2025-08-09: 統一ロギングシステム完全実装
- 2025-08-09: 段階的移行完了（99.5%成功率）
- 2025-08-09: 品質ゲート・Pre-commitフック実装


### Domain 層のベストプラクティス（更新）
- console 出力は `noveler.domain.utils.domain_console.get_console()` を経由。
- logger は `ILogger/NullLogger`（または `ILoggerService/NullLoggerService`）を使用し、未注入時は Null を既定。
- Infra 機能は importlib 遅延参照または manager/proxy を経由してアクセス。

