Observability
Customer Portal currently writes application and migration messages to standard output and error. PostgreSQL and Resend provide additional service-level signals, while invoice email history records provider message state in the database.
There is not yet a dedicated health endpoint, structured logging contract, application metrics, distributed tracing, or bundled error-tracking integration. Treat those as contribution opportunities, not as existing capabilities.
Minimum monitoring baseline
| Signal | Alert when | Why it matters |
|---|---|---|
| Process and restarts | the service is unavailable or repeatedly restarts | migration or startup failure can prevent Nuxt from serving |
| HTTPS probe | / fails, times out, or has abnormal latency | confirms public routing and the Node process |
| PostgreSQL | connections, CPU, memory, storage, locks, or query latency cross safe limits | most authenticated and feature workflows depend on the database |
| HTTP errors | 5xx rate or latency changes materially | catches application regressions that a homepage probe misses |
| Migration output | the release job or Docker entrypoint exits non-zero | new code must not run against an unexpected schema |
| Authentication email | send errors or prerequisite warnings appear | verification, invitations, OTP, and recovery can stop working silently for users |
| Invoice delivery | failed or persistently pending messages increase | invoices can be generated successfully but not delivered |
| Backups | the newest verified backup exceeds the RPO | availability without recoverability is incomplete |
| Restore drills | no successful drill exists within the agreed interval | a stored archive may still be unusable |
An HTTP probe of / confirms only the public web path. It does not prove PostgreSQL, authentication, authorization, OAuth, or email delivery are healthy.
Release smoke checks
After every production release, run a small set of controlled checks:
- load the homepage and sign-in page over the public HTTPS origin;
- authenticate with a non-privileged test account;
- select its expected organization and load a protected page;
- read a representative, database-backed feature view;
- exercise any workflow changed by the release;
- inspect startup, migration, server, database, and provider signals.
Keep routine smoke checks non-destructive. Do not create invoices, send customer email, approve time, or mutate financial records unless the deployment has dedicated synthetic data and cleanup rules.
Handle logs as sensitive data
Current log messages can include request paths, email addresses, subjects, organization context, and provider errors. Restrict access and retention. Never log cookies, authorization headers, OAuth tokens, password-reset links, OTPs, API keys, database URLs, attachment bodies, or complete request payloads.
When sharing an incident excerpt, redact personal data and secrets while preserving the timestamp, source revision, route pattern, error type, and correlation information needed for diagnosis.
Recommended instrumentation work
A production-focused contribution should introduce these capabilities as explicit, reviewed contracts:
- structured server logs with request or correlation IDs;
- redaction at the logging boundary;
- a process-only liveness endpoint and a database-aware readiness endpoint;
- request rate, latency, error, job, email, and migration metrics;
- error tracking with source revision and deployment environment;
- documented retention, access, privacy, and alert ownership.
Keep liveness independent of PostgreSQL so an orchestrator does not restart healthy processes during a database outage. Readiness may fail when the application cannot safely serve database-backed traffic. Avoid returning configuration, dependency versions, database details, or secrets from either endpoint.
Propose this work as a reusable module or core capability in module proposals.