ngit-grasp/d8da-adopt-structured-logging.md

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:

tracing::warn!(
    "[PARSE_FAIL] kind={} event_id={}... reason=\"{}\" repo={} npub={}",
    kind, event_id, reason, repo, npub
);

After:

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