Observability & Logging rules

Never swallow exceptions silently; wrap with context and rethrow or translate to a domain exception.

Logging/metrics must redact or hash personal data; attach lawful_basis and purpose to diagnostic context; forbid raw PII in logs. (GDPR Art. 5(1)(c) data minimization)

Do not use printStackTrace/System.err; log via a structured logger with context and level.

Avoid bare `rescue`; rescue StandardError (or a narrower class) and log with context.

Attach a trace_id (e.g., from request header or generated UUID) and emit structured JSON logs for login, role change, and data export routes.

Background jobs must throw on irrecoverable failures (after logging) so the runner/queue can retry or dead-letter appropriately.

If a PR changes an API endpoint/controller/route, assess current production health before adding heavier logic. - If a monitoring MCP is available (Datadog/Grafana): query current p95 latency and error rate for that endpoint. - If the endpoint is already degraded, warn against adding heavy queries, blocking I/O, or complex synchronous logic; require performance evidence or a safe rollout plan. To enable this check, the PR should reference the endpoint path (e.g., `POST /api/payments`) or the controller/action name.

For any handler that reads or writes ePHI, write an append-only audit record with user id, patient id, action (READ_PHI/WRITE_PHI), purpose-of-use, timestamp, and request id. Prevent deletion or mutation of audit entries.

Include request-scoped fields (method, path, request_id, deadline/canceled) in error logs. Pass context through layers.

Tag code owners or subject-matter experts for impacted areas. Include a short 'What to review' section to guide each reviewer.

Populate MDC with userId and traceId; include them in log pattern; log security events as JSON.

Ensure that console statements are removed in production code. Console logs can expose sensitive data and impact performance.

Do not use the error‐suppression operator '@' before function calls or expressions. Instead, handle potential errors properly using return checks or exceptions (try/catch).

Implement a scheduled worker to delete or anonymize records past expires_at, with metrics on deletions and failures. Dry-run mode allowed only in non-prod.

Use `catch (e, stack)` and log both exception and stack; do not log message-only.

Implement a tracing layer that scans fields and redacts patterns (JWT, API keys, emails) before output.

Always handle or log caught exceptions instead of silently ignoring them to improve debugging and maintain application stability.

Avoid empty catch blocks. When you catch an exception, implement meaningful handling: log the error, perform a fallback action, or rethrow after processing. Do not catch exceptions generically just to suppress them.

Prefer key-value or JSON logging over string concatenation; include correlation/request IDs from CoroutineContext when available.

Use $dontFlash in app/Http/Middleware/TrimStrings.php or logging processors to redact 'password', 'token', 'ssn', and emails.

Register a Monolog processor to mask emails/phones and attach pii_redacted:true; forbid direct logging of raw identifiers.

In when/else or default branches, log a warning with the unexpected value to surface silent failures.

Guard expensive debug log formatting behind level checks or lazy formatting.

Intercept Authorization headers and redact bearer/JWT values; attach requestId to every log line.