pr_payload.json

{
  "title": "feat: structured logging and correlation propagation across services (#113)",
  "head": "feature/113-log-correlation-propagation",
  "base": "main",
  "body": "## Summary\n\nThis PR implements structured logging with end-to-end correlation propagation for StreamPay settlement flows. The system uses AsyncLocalStorage to propagate correlation context across API → Queue → Worker → Chain → Webhook, enabling tracing of requests from API edge through all processing steps.\n\n## Propagation Flow\n\n1. **API Edge**: `withCorrelationMiddleware` extracts/generates request_id and correlation_id from headers\n2. **Queue Enqueue**: Job metadata includes correlation context (request_id, correlation_id, stream_id, traceparent)\n3. **Worker Processing**: Context restored from job metadata, job-specific context added (job_id, queue_name, retry_count)\n4. **Chain Submission**: Stellar service adds stellar_tx_hash to correlation context\n5. **Webhook Emission**: Webhook service adds webhook_id, internal headers stripped before external delivery\n6. **Response**: Safe correlation headers returned to client\n\n## Before/After Log Examples\n\n### Before (Unstructured):\n```\n[2026-04-28 10:30:00] Stream settled\n[2026-04-28 10:30:01] Transaction submitted\n[2026-04-28 10:30:02] Error: transaction failed\n```\n\n### After (Structured with Full Propagation):\n```json\n{\"level\":\"info\",\"message\":\"Incoming request\",\"timestamp\":\"2026-04-28T10:30:00.000Z\",\"service\":\"streampay-frontend\",\"environment\":\"production\",\"request_id\":\"req-abc123\",\"correlation_id\":\"corr-def456\",\"method\":\"POST\",\"url\":\"/api/streams/stream-ada/settle\"}\n\n{\"level\":\"info\",\"message\":\"Settlement job enqueued\",\"timestamp\":\"2026-04-28T10:30:00.200Z\",\"service\":\"streampay-frontend\",\"environment\":\"production\",\"request_id\":\"req-abc123\",\"correlation_id\":\"corr-def456\",\"stream_id\":\"stream-ada\",\"job_id\":\"job-xyz789\",\"queue_name\":\"settlement-queue\"}\n\n{\"level\":\"info\",\"message\":\"Worker processing job\",\"timestamp\":\"2026-04-28T10:30:00.300Z\",\"service\":\"streampay-frontend\",\"environment\":\"production\",\"request_id\":\"req-abc123\",\"correlation_id\":\"corr-def456\",\"stream_id\":\"stream-ada\",\"job_id\":\"job-xyz789\",\"queue_name\":\"settlement-queue\",\"attempt\":1}\n\n{\"level\":\"info\",\"message\":\"Stellar transaction submitted to RPC\",\"timestamp\":\"2026-04-28T10:30:00.700Z\",\"service\":\"streampay-frontend\",\"environment\":\"production\",\"request_id\":\"req-abc123\",\"correlation_id\":\"corr-def456\",\"stream_id\":\"stream-ada\",\"stellar_tx_hash\":\"stellar-tx-abc123\"}\n\n{\"level\":\"info\",\"message\":\"Webhook delivered successfully\",\"timestamp\":\"2026-04-28T10:30:01.250Z\",\"service\":\"streampay-frontend\",\"environment\":\"production\",\"request_id\":\"req-abc123\",\"correlation_id\":\"corr-def456\",\"stream_id\":\"stream-ada\",\"webhook_id\":\"webhook-def456\",\"status_code\":200}\n```\n\n## Security Notes\n\n- **Header Spoofing Prevention**: External clients cannot override internal correlation IDs. Untrusted requests receive fresh correlation IDs via `sanitizeCorrelationHeaders()`.\n- **Internal Header Stripping**: Headers like `x-internal-auth`, `x-service-token` are never exposed in responses via middleware.\n- **PII Policy**: No automatic PII logging. Sensitive data must be explicitly added by developers with caution.\n- **Auth/Keys**: JWT secrets remain in environment variables, never logged.\n\n## Worker Log Proof\n\nWorker logs include restored correlation context:\n- `job_id` from job metadata\n- `queue_name` from job metadata\n- `retry_count` incremented on retries\n- Original `correlation_id` preserved from API edge\n- `stream_id` and `stellar_tx_hash` propagated through chain submission\n\n## Queue Propagation Proof\n\nQueue jobs store correlation context in metadata:\n- `job.correlationContext.request_id`\n- `job.correlationContext.correlation_id`\n- `job.correlationContext.stream_id`\n- `job.correlationContext.traceparent`\n\nWorker restores this context before processing via `withCorrelationContext()`.\n\n## Assumptions Verified\n\n- Repository is a Next.js frontend with API routes (mock queue/worker/stellar/webhook services added for demonstration)\n- AsyncLocalStorage is available in Node.js 18+ (matches project prerequisites)\n- All API routes follow Next.js App Router patterns\n\n## Intentional Exclusions\n\n- OpenTelemetry integration (can be added later for distributed tracing)\n- Real BullMQ/RabbitMQ integration (mock queue used for demonstration)\n- Real Stellar network integration (mock service used for demonstration)\n- Real webhook delivery (mock service used for demonstration)\n\n## Tests Implemented\n\n- Correlation context extraction from headers\n- AsyncLocalStorage propagation through async operations\n- Header spoofing prevention for external clients\n- Public boundary header stripping\n- Structured logging format validation\n- PII safety (no auto-inclusion of sensitive data)\n- Queue job enqueue with correlation context\n- Worker context restoration from job metadata\n- Retry context tracking\n- Stellar transaction logging with tx_hash\n- Webhook emission with header stripping\n\n## Documentation\n\nAdded `docs/observability-tracing-guide.md` with:\n- Complete propagation flow (API → Queue → Worker → Chain → Webhook)\n- How to trace failed settlements\n- Log search patterns for Datadog/ELK/CloudWatch\n- Before/after log examples with full propagation\n- Security notes and PII policy\n- Integration guidance for future backend services\n\nClose #113"
}