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:
nyash-codex
2025-12-03 14:07:01 +09:00
parent 6ecd8f7f52
commit 8203882a97
3 changed files with 525 additions and 1 deletions

View File

@ -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.logRust側と連携可能将来拡張
### 設計原則(.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