docs(phase 104): .hako側ロギング設計ガイド確立

- Add Section 4 (.hako側ロギング方針) to logging_policy.md - Create hako_logging_design.md (comprehensive guide, 331 lines) - Define 4 logging categories (user-facing/dev-debug/monitoring/internal Rust) - Provide 3 logging box patterns (Lightweight/Structured/Contextual) - Add best practices and anti-patterns with code examples - Update ring0-inventory.md with Phase 104 entry - Cross-reference documentation for consistency This completes Phase 104: establishing user-facing logging guidelines for Nyash applications, complementing Rust-side logging policy from Phase 99-101. Files modified: - docs/development/current/main/logging_policy.md - docs/development/current/main/hako_logging_design.md (new) - docs/development/current/main/ring0-inventory.md Related: Phase 99 (logging policy design), Phase 100-101 (Rust impl)
2025-12-03 14:07:01 +09:00
parent 6ecd8f7f52
commit 8203882a97
3 changed files with 525 additions and 1 deletions
--- a/docs/development/current/main/hako_logging_design.md
+++ b/docs/development/current/main/hako_logging_design.md
@ -0,0 +1,331 @@
+# Phase 104: .hako側ロギング設計ガイド
+
+## 概要
+
+Nyash(.hako)アプリケーションからのロギングを体系的に設計し、Ring0.log（Rust内部）
+との役割分担を明確にする。
+
+## Architecture: 3層ロギングの完全図
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  ユーザーアプリケーション (.hako)                        │
+│                                                          │
+│  box MyApp {                                            │
+│    main() {                                             │
+│      me.console.println("Result: OK")  ← ConsoleBox     │
+│    }                                                    │
+│  }                                                      │
+└──────────────────┬──────────────────────────────────────┘
+                   │
+              ConsoleService
+              (user-facing)
+                   │
+┌──────────────────▼──────────────────────────────────────┐
+│  Rust Runtime (Ring0.log)                               │
+│                                                          │
+│  ring0.log.debug("[joinir] Processing...")      ← internal
+│  ring0.log.error("VM error: {}")                ← internal
+└──────────────────┬──────────────────────────────────────┘
+                   │
+                stderr/stdout
+                   │
+           ┌───────▼────────┐
+           │  Terminal      │
+           │  (user sees)   │
+           └────────────────┘
+```
+
+## ロギングの4つのカテゴリ
+
+### 1. User-Facing (ユーザー向け)
+
+**属性**: 常に表示（本番環境対応）
+**出力先**: ConsoleBox → stdout
+**制御**: フラグなし（常時有効）
+
+**例**:
+```nyash
+box FileProcessor {
+    console: ConsoleBox
+
+    process(filename) {
+        me.console = new ConsoleBox()
+
+        if file_not_found(filename) {
+            me.console.println("❌ File not found: " + filename)
+            return -1
+        }
+
+        me.console.println("✅ Processing: " + filename)
+        return 0
+    }
+}
+```
+
+### 2. Dev-Debug (開発用デバッグ)
+
+**属性**: 開発時のみ（本番環境では削除推奨）
+**出力先**: println!（局所的）
+**制御**: bool flag（環境変数or定数）
+
+**例**:
+```nyash
+box MathBox {
+    DEBUG: BoolBox = false  // 環境変数から設定
+
+    calculate(a: Integer, b: Integer) {
+        if DEBUG {
+            print("[DEBUG] a=" + a + ", b=" + b)
+        }
+        return a + b
+    }
+}
+```
+
+### 3. Monitoring (運用監視)
+
+**属性**: 定期レポート（本番環境で有効）
+**出力先**: ConsoleBox → stdout
+**制御**: 定期的（タイマーベース）
+
+**例**:
+```nyash
+box ServiceMonitor {
+    console: ConsoleBox
+    requests_count: IntegerBox
+
+    tick() {
+        me.console = new ConsoleBox()
+        me.console.println("[PERF] Requests/sec: " + me.requests_count)
+        me.requests_count = 0
+    }
+}
+```
+
+### 4. Internal Rust (内部実装)
+
+**属性**: Rust実装の内部ログ
+**出力先**: Ring0.log → stderr
+**制御**: NYASH_RING0_LOG_LEVEL
+
+**例** (.hako側には関係ない、参考):
+```rust
+// src/mir/builder.rs
+ring0.log.debug("[mir] Building function...");
+```
+
+## ロギングBox設計パターン
+
+### パターン 1: Lightweight Logger
+
+用途: 単純なユースケース（メッセージのみ）
+
+```nyash
+box SimpleLogger {
+    console: ConsoleBox
+
+    birth() {
+        me.console = new ConsoleBox()
+    }
+
+    log(msg) {
+        me.console.println(msg)
+    }
+}
+
+// 使用例
+box MyApp {
+    main() {
+        local logger = new SimpleLogger()
+        logger.log("Processing...")
+        logger.log("✅ Done")
+    }
+}
+```
+
+### パターン 2: Structured Logger
+
+用途: レベル分け（ERROR/WARN/INFO）
+
+```nyash
+box StructuredLogger {
+    console: ConsoleBox
+
+    birth() {
+        me.console = new ConsoleBox()
+    }
+
+    error(msg) {
+        me.console.println("[ERROR] " + msg)
+    }
+
+    warn(msg) {
+        me.console.println("[WARN] " + msg)
+    }
+
+    info(msg) {
+        me.console.println("[INFO] " + msg)
+    }
+}
+
+// 使用例
+box DatabaseConnector {
+    logger: StructuredLogger
+
+    birth() {
+        me.logger = new StructuredLogger()
+    }
+
+    connect(host) {
+        if network_unavailable() {
+            me.logger.error("Network unavailable")
+            return false
+        }
+
+        me.logger.info("Connected to: " + host)
+        return true
+    }
+}
+```
+
+### パターン 3: Contextual Logger
+
+用途: コンテキスト情報を含むログ
+
+```nyash
+box ContextualLogger {
+    console: ConsoleBox
+    context: StringBox  // operation_id等
+
+    birth(ctx) {
+        me.console = new ConsoleBox()
+        me.context = ctx
+    }
+
+    log(msg) {
+        me.console.println("[" + me.context + "] " + msg)
+    }
+}
+
+// 使用例
+box RequestHandler {
+    logger: ContextualLogger
+
+    birth(request_id) {
+        me.logger = new ContextualLogger(request_id)
+    }
+
+    process() {
+        me.logger.log("Request started")
+        // ... 処理 ...
+        me.logger.log("Request completed")
+    }
+}
+```
+
+## ベストプラクティス
+
+### ✅ DO (推奨)
+
+1. **一元化**: ロギングBoxを1つ所有
+   ```nyash
+   box MyApp {
+       logger: LoggerBox  // ← 一箇所だけ
+       main() { ... }
+   }
+   ```
+
+2. **構造化**: メッセージは構造化
+   ```nyash
+   logger.log("[OPERATION] " + op_name + " status=" + status)
+   ```
+
+3. **条件付き**: デバッグログにフラグ
+   ```nyash
+   if debug_enabled {
+       logger.debug("var=" + var)
+   }
+   ```
+
+### ❌ DON'T (回避)
+
+1. **散乱**: 複数の ConsoleBox 初期化
+   ```nyash
+   // ❌ ダメ
+   box MyApp {
+       main() {
+           local c1 = new ConsoleBox()
+           local c2 = new ConsoleBox()  // 重複
+       }
+   }
+   ```
+
+2. **混在**: データ処理ロジックとログ混在
+   ```nyash
+   // ❌ ダメ
+   box Processor {
+       process(x) {
+           print(x)  // ← ロジックに埋め込み
+           return x + 1
+       }
+   }
+   ```
+
+3. **過剰**: 全行でログ出力
+   ```nyash
+   // ❌ ダメ
+   calculate(a, b) {
+       print("enter")
+       local x = a + b
+       print("x=" + x)
+       print("exit")
+       return x
+   }
+   ```
+
+## ロギング制御フロー
+
+```
+┌─────────────────┐
+│ .hako app start │
+└────────┬────────┘
+         │
+    ┌────▼──────────────────────────┐
+    │ Check NYASH_RING0_LOG_LEVEL env │
+    └────┬──────────────────────────┘
+         │
+    ┌────▼────────────┐      ┌──────────────────┐
+    │ DEBUG level?    │─Y─>  │ Enable full logs │
+    └────┬────────────┘      └──────────────────┘
+         │
+         N
+    ┌────▼────────────┐      ┌──────────────────┐
+    │ INFO level?     │─Y─>  │ Error/Warn only  │
+    └────┬────────────┘      └──────────────────┘
+         │
+         N  (default)
+    ┌────▼──────────────┐
+    │ User-facing only  │
+    │ (ConsoleBox)      │
+    └───────────────────┘
+```
+
+## チェックリスト: ロギング設計確認
+
+実装時には以下をチェック:
+
+- [ ] ConsoleBox初期化は1回のみ
+- [ ] ユーザーメッセージは全て ConsoleBox経由
+- [ ] デバッグログに "[DEBUG]" prefix
+- [ ] エラーメッセージに "❌" 絵文字
+- [ ] 成功メッセージに "✅" 絵文字
+- [ ] ロギングLogicを別Boxに分離した
+- [ ] テストコード内の println! は許容
+- [ ] 本番環境での不要なログを削除した
+
+## 関連ドキュメント
+
+- [logging_policy.md](logging_policy.md) - Rust/Ring0.log側方針
+- [ring0-inventory.md](ring0-inventory.md) - println!分類在庫
+- [core_optional_design.md](core_optional_design.md) - Optional化設計