[Phase 1] Observability Baseline (Structured Logging & Metrics)

[syed-reza98]

Priority: P0 (Critical)

Phase: 1 - E-Commerce Core
Estimate: 2 days
Type: Story

Context

Establish minimal observability: structured JSON logging, domain event logs, metrics counters/gauges for critical subsystems (payments, inventory, idempotency, webhooks).

Scope

• Logging utility wrapper (pino or console structured) log.info({evt, ...context})
• Correlation ID middleware (request-scoped, include in logs)
• Metrics facade (in-memory dev; future Prometheus) with simple increment/observe APIs
• Emit metrics: payment.attempt.count, idempotency.replay.count, inventory.reservation.active, webhook.delivery.success/failure
• Error logging with stack, route, orgId, userId (if available)

Acceptance Criteria

• All domain actions log structured event (key: evt)
• Correlation ID present across chained logs within request scope
• Metrics counters increment visible via temporary /api/debug/metrics endpoint (dev only)
• Sensitive data (secrets, tokens) excluded from logs
• Performance overhead < 3% of request time (qualitative dev measurement)

Example Log Shape

{
  "level": "info",
  "evt": "inventory_reservation_created",
  "reservationId": "res_123",
  "productId": "prod_42",
  "orgId": "org_9",
  "correlationId": "req_abcd",
  "durationMs": 12
}

Dependencies

• Supports debugging for Idempotency ([Phase 1] Idempotency Key & Request Replay Safety Layer #66), Webhooks ([Phase 1] Webhook Infrastructure & Delivery Guarantees #69), Inventory ([Phase 1] Inventory Reservation & Hold System #64)
• Pre-req for future SLO tracking

Metrics Targets

• Coverage: >= 90% of P0 domain actions logged
• Zero PII leakage (manual inspection)

Testing Checklist

• Log emitted for reservation create
• Correlation ID consistent across payment attempt sequence
• Metrics endpoint returns increments

Risk

Without baseline, debugging & reliability degrade (score: 15). Foundational for scale.

References

• docs/GITHUB_ISSUES_COMPARISON_ANALYSIS.md (observability gap)