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)
This commit is contained in:
@ -292,8 +292,187 @@ Focus on high-impact migrations first, defer low-priority changes.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
## Section 4: .hako側ロギング方針 (Phase 104)
|
||||
|
||||
### 概要
|
||||
|
||||
Nyash(.hako)アプリケーションからのロギングは、ConsoleBoxを通じてユーザーに伝える方式に統一。
|
||||
|
||||
### パターン分類
|
||||
|
||||
#### Pattern 1: ユーザー向けメッセージ(user-facing)
|
||||
|
||||
**用途**: ユーザーに表示される情報
|
||||
- エラーメッセージ
|
||||
- 進捗情報
|
||||
- 成功/完了通知
|
||||
|
||||
**実装方法**:
|
||||
```nyash
|
||||
box MyApp {
|
||||
console: ConsoleBox
|
||||
|
||||
main() {
|
||||
me.console = new ConsoleBox()
|
||||
|
||||
// ✅ 正しい方法: ConsoleBox経由
|
||||
me.console.println("Processing started...")
|
||||
|
||||
// 実装例: エラーハンドリング
|
||||
if error_occurred {
|
||||
me.console.println("❌ Error: " + error_msg)
|
||||
return 1
|
||||
}
|
||||
|
||||
me.console.println("✅ Success!")
|
||||
return 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**ガイドライン**:
|
||||
- すべてのユーザー向けメッセージは ConsoleBox.println() 使用
|
||||
- エラーメッセージは "❌" 絵文字で開始
|
||||
- 成功メッセージは "✅" 絵文字で開始
|
||||
- 進捗は "[1/10]" などの形式で表示
|
||||
|
||||
#### Pattern 2: デバッグ/診断ログ(dev-debug)
|
||||
|
||||
**用途**: 開発時のデバッグ情報
|
||||
- 変数値のダンプ
|
||||
- 関数entry/exit
|
||||
- 分岐の選択記録
|
||||
|
||||
**実装方法** (Phase 104では ユーザーアプリ側は println! 許容):
|
||||
```nyash
|
||||
box MyApp {
|
||||
main() {
|
||||
// 現在: ユーザーアプリが debug print 時は println! OK
|
||||
// 将来 (Phase 105): ユーザー定義ロギングフレームワーク検討
|
||||
|
||||
local debug_enabled = false // 環境変数から読む
|
||||
if debug_enabled {
|
||||
print("[DEBUG] Processing item: " + item_id)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**ガイドライン**:
|
||||
- デバッグ出力は "[DEBUG]" prefix で統一
|
||||
- bool flag で on/off 制御(環境変数参照)
|
||||
- 本番環境では全削除推奨
|
||||
|
||||
#### Pattern 3: 監視/メトリクス(monitoring)
|
||||
|
||||
**用途**: 運用時の監視情報
|
||||
- 実行時間計測
|
||||
- メモリ使用量
|
||||
- 処理レート
|
||||
|
||||
**実装方法**:
|
||||
```nyash
|
||||
box PerformanceMonitor {
|
||||
console: ConsoleBox
|
||||
start_time: IntegerBox
|
||||
|
||||
begin() {
|
||||
me.console = new ConsoleBox()
|
||||
me.start_time = runtime.now()
|
||||
}
|
||||
|
||||
report() {
|
||||
local elapsed = runtime.now() - me.start_time
|
||||
me.console.println("[PERF] Elapsed: " + elapsed + "ms")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**ガイドライン**:
|
||||
- メトリクスは "[PERF]" prefix で統一
|
||||
- 定期レポーティング推奨
|
||||
- Ring0.log(Rust側)と連携可能(将来拡張)
|
||||
|
||||
### 設計原則(.hako側視点)
|
||||
|
||||
1. **Single Responsibility**: 各Boxは1つのロギング目的に専念
|
||||
2. **Testability**: ログ出力をテスト可能にする(interface化)
|
||||
3. **Composability**: ロギングBoxを組み合わせる
|
||||
4. **Zero Config Default**: 環境変数なしでもロギング動作
|
||||
|
||||
### アンチパターン(避けるべき書き方)
|
||||
|
||||
```nyash
|
||||
// ❌ ダメな例 1: raw println!を散乱
|
||||
print("value: " + x) // → Boxにロギング機能を出す
|
||||
|
||||
// ❌ ダメな例 2: ConsoleBoxの多重初期化
|
||||
box MyBox {
|
||||
main() {
|
||||
local console = new ConsoleBox()
|
||||
console.println("msg1")
|
||||
|
||||
local console2 = new ConsoleBox() // ← 重複初期化
|
||||
console2.println("msg2")
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ ダメな例 3: ロギングロジック混在
|
||||
box DataProcessor {
|
||||
process(data) {
|
||||
if validate(data) {
|
||||
print("OK") // ← 出力ロジックが混在
|
||||
return process_data(data)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正しい例: 責務分離
|
||||
box DataProcessor {
|
||||
logger: LoggerBox
|
||||
|
||||
process(data) {
|
||||
if validate(data) {
|
||||
return process_data(data)
|
||||
} else {
|
||||
me.logger.error("Validation failed")
|
||||
return null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 今後の拡張予定
|
||||
|
||||
**Phase 105**: ユーザー定義ロギングフレームワーク
|
||||
- Logger Box interface化
|
||||
- ログレベル統一(DEBUG/INFO/WARN/ERROR)
|
||||
- Structured logging (JSON形式)
|
||||
|
||||
**Phase 106**: ログ出力先の切り替え
|
||||
- ConsoleBox → FileBox
|
||||
- ConsoleBox → NetworkBox
|
||||
- Pluggable logger architecture
|
||||
|
||||
### テストでのロギング
|
||||
|
||||
テストコード内のロギング/println!は許容:
|
||||
```nyash
|
||||
// ✅ テストコード内
|
||||
test my_test {
|
||||
local result = my_function()
|
||||
print("Result: " + result) // テスト内 OK
|
||||
assert(result == expected)
|
||||
}
|
||||
```
|
||||
|
||||
**理由**: テストは隔離環境実行のため、ログ管理の必要がない
|
||||
|
||||
---
|
||||
|
||||
## 関連ドキュメント
|
||||
|
||||
- [.hako側ロギング設計](hako_logging_design.md) - Phase 104 ユーザーアプリ視点
|
||||
- [Ring0 Inventory](ring0-inventory.md) - println! categorization and Ring0.log plans
|
||||
- [CoreBoxes Design - Section 15.6-A](core_boxes_design.md#section-156-a-logsoutput-unified-design) - Architectural context
|
||||
- [Phase 85 CURRENT_TASK](../../../CURRENT_TASK.md) - Implementation timeline
|
||||
|
||||
Reference in New Issue
Block a user