issue: create d8da - adopt structured logging

2026-10-05 15:08:24 +00:00 · 2026-01-23 12:10:27 +00:00
parent 7821fb7b75
commit fd2a0a61ba
1 changed files with 72 additions and 0 deletions
@@ -0,0 +1,72 @@
+# Adopt Structured Logging Throughout ngit-grasp
+
+**ID:** d8da
+**Priority:** Low
+
+## Problem
+
+Currently, ngit-grasp uses formatted string logging (e.g., `tracing::info!("message with {}", value)`). While this is human-readable and grep-friendly, it limits:
+
+- Log aggregation and querying (Loki, Elasticsearch, etc.)
+- Metrics extraction from logs
+- Consistent field naming across the codebase
+- Machine-readable log parsing
+
+**Current state:**
+- Migration analysis logging uses formatted strings like `[PARSE_FAIL] kind=30618 event_id=abc... reason="..." repo=myrepo npub=npub1...`
+- This format works well for grep/awk but isn't true structured logging
+- The `tracing` crate supports proper structured logging with field extraction
+
+## Plan
+
+- [ ] Phase 1: Audit all logging calls in the codebase
+- [ ] Phase 2: Define standard field names (e.g., `repo`, `npub`, `event_id`, `kind`)
+- [ ] Phase 3: Convert logging to use structured fields (can be done incrementally)
+- [ ] Phase 4: Add configuration option for log format (human-readable vs JSON)
+- [ ] Phase 5: Update documentation
+
+## Proposed Solution
+
+Convert logging throughout ngit-grasp to use structured fields:
+
+**Before:**
+```rust
+tracing::warn!(
+    "[PARSE_FAIL] kind={} event_id={}... reason=\"{}\" repo={} npub={}",
+    kind, event_id, reason, repo, npub
+);
+```
+
+**After:**
+```rust
+tracing::warn!(
+    kind = %kind,
+    event_id = %event_id,
+    reason = %reason,
+    repo = %repo,
+    npub = %npub,
+    "[PARSE_FAIL]"
+);
+```
+
+**Benefits:**
+- Better integration with log aggregation systems
+- Easier metrics extraction (e.g., count parse failures by kind)
+- Consistent field naming convention
+- Both human-readable AND machine-parseable
+- Can output JSON format for production environments
+
+## Progress
+
+### 2026-01-23 [Session - Issue Creation]
+- Created issue to track structured logging adoption
+- Identified during logging review for issue 4bc5 (relay.ngit.dev migration)
+- Marked as low priority - nice-to-have, not urgent
+
+## Notes
+
+- **Dependencies:** None (can be done incrementally)
+- **Scope:** Can be done one module at a time
+- **Backward compatibility:** Should maintain compatibility with existing log parsing tools
+- **Production consideration:** Consider adding a JSON output option for production deployments
+- **Related work:** Identified during issue 4bc5 logging review