Skip to main content

Observability

This document describes observability behavior that exists in the current implementation.

Request Correlation​

Inbound​

correlationMiddleware in apps/api/src/middleware/correlation.ts:

  • reads incoming x-correlation-id if present,
  • otherwise generates id via generateCorrelationId() (req_<hex>),
  • stores it in request context,
  • emits X-Correlation-Id in response.

Error propagation​

requestId in API error responses maps to the correlation id.

Structured Logging​

Shared logger is in packages/observability/src/logger.ts.

Features:

  • Pino JSON logs
  • level from LOG_LEVEL
  • ISO timestamps
  • centralized redaction of common PII paths

Redacted examples include:

  • email, mobile
  • req.headers.authorization
  • nested user/customer email/mobile fields

Sentry Integration​

Sentry is initialized in apps/api/src/index.ts through initSentry(...).

Behavior:

  • disabled when DSN is absent,
  • environment-aware trace sampling,
  • beforeSend strips user-level PII fields.

Error Normalization​

Global error handling in apps/api/src/middleware/error-handler.ts maps known exceptions to standard shape:

{
  "code": "...",
  "message": "...",
  "requestId": "req_..."
}

Validation errors include flattened issues details.

Unhandled errors are logged and returned as INTERNAL_ERROR.

Operational Signals to Track​

Recommended top-level views:

  1. route-level 4xx/5xx rates,
  2. webhook processing failures,
  3. poll cron failures and per-connection errors,
  4. auth/profile failure rates by status code,
  5. admin action audit volume.

Production Practices​

  1. Set LOG_LEVEL=info in production.
  2. Set SENTRY_DSN for server error capture.
  3. Preserve X-Correlation-Id from clients and proxies.
  4. Never log decrypted tokens or raw secrets.
Last updated on
Written byDhruv Doshi