Observability & Logging code review rules

Handlers must verify the requester’s role and a valid consent/relationship (e.g., care team assignment) before disclosing ePHI; include Purpose-Of-Use in the decision and audit the outcome.

Never emit Primary Account Number (PAN) or Sensitive Authentication Data (SAD: CVV/CVC, full track data, PIN) to application or audit logs. Per PCI DSS 4.0 Req. 3 and 10, always mask PAN as first6last4 and fully redact SAD before logging.

Log failures with operation name, key identifiers, and exception; prefer structured logging (fields).

Wrap HTTP/SDK calls with timeouts and catch transport/errors; log context and map to domain failures.

Guard app startup with zone-level handlers and FlutterError hooks; surface fatal errors and report them.

Log key operations with structured fields (actor/resource/operation) at appropriate levels; include exception info on failures.

Serve via rustls with TLS1.2+ and add middleware to log JSON audit events with user_id and request_id; never log raw tokens.

Surround network and IPC calls with try/catch for IOException and timeouts; map to domain errors and log context.

Whenever PII is read, emit an audit event capturing actor, purpose, fields touched, and legal basis; never include raw PII in the audit payload—store hashes/tokens only.

Ensure that catch blocks do not remain empty. Empty catch blocks hide errors, making debugging difficult. Recommend logging or handling errors properly.

Ensure that logging arguments and preconditions do not require costly evaluations before method calls.

If the PR claims to fix a specific issue (e.g., 'Fixes #123' / 'Fix PAY-123'), validate it against the real production error. - If an observability MCP is available (Sentry/Datadog/Bugsnag): fetch the event/stack trace and confirm the change addresses the root cause. - Require a regression test (or a clearly documented reason why a test cannot be added). Call out fixes that only hide symptoms (catch-and-ignore, broader retries, defaulting values) without removing the underlying failure mode.

Configure your application not to display detailed error messages (stack traces, PHP warnings) to end users in production. Instead, log errors for developers and show a generic message to users.

Ensure that all caught exceptions are either logged or handled properly. Empty catch blocks are not allowed.

Never write Protected Health Information (PHI/ePHI) to logs. Redact fields like name, SSN, MRN, DOB, address, diagnoses, and lab results; store only non-identifying metadata and a stable request trace id. If logging is required for troubleshooting, replace values with consistent tokens and record access separately in the audit log.

On every create/read/update/delete of CHD or tokens, write a structured audit event (who, what, when, result) without full PAN, including only pan_last4. Persist to an append-only/immutable sink. (PCI DSS 4.0 Req. 10)

Every security-relevant action must append to an immutable, append-only audit log with fields: timestamp (UTC ISO8601), actor.user_id, actor.role, action, resource.id, result, trace_id, ip, user_agent. Logs must be signed or stored in WORM/immutable storage and forwarded to a SIEM.

Never silently ignore an error, and avoid handling an error (e.g., logging it) and then still returning it. Either handle the error fully or propagate it upward, but not both.

Log errors with operation name and identifiers (e.g., userId, orderId) using structured context.

Error logs must include the operation name and relevant identifiers as structured fields, not just a message string.

Emergency access to ePHI must go through a dedicated break_glass path that requires reason, approver, limited time window, and automatic post-incident review. The PR must include changes to the audit log schema and runbook.

Every catch block must log or report the error at least once before handling or rethrowing.

Before emitting logs, detect and redact PII and secret patterns (emails, tokens, keys). Replace values with consistent hashes or tokens; never log full credentials.

Never write raw personal data to logs. Apply irreversible masking/redaction (e.g., CPF → ..-; emails → f**@domain.com). Include the LGPD purpose in the log context and prefer structured logging.

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.

Configure Monolog to add a processor that redacts emails, tokens, and SSNs before writing logs; include request_id.

Wrap logger to filter emails and tokens using regex before logging; include trace_id in every entry.

Delete Console.WriteLine, Debug.WriteLine, and temporary diagnostics before merging; rely on structured logging.

Do not use echo/var_dump for diagnostics in application code; use a PSR-3 logger or error_log with levels.

Use the standard logging module (or your app's logger) instead of print() in committed code.

Add middleware to set HSTS, X-Content-Type-Options, and secure cookies; log JSON with actor and trace_id for auth and admin routes.

Emit JSON audit events via ActiveSupport::Notifications with user_id, action, resource_id, and request_id.

Log security events via ILogger with properties {Action, UserId, ResourceId, Result, TraceId}; configure sink to JSON and send to SIEM.

Mark columns and event fields with pii and purpose metadata; prefer hashed or tokenized variants in telemetry. Use these tags to auto-generate Records of Processing Activities (RoPA). (GDPR Art. 30)

Emit stable message keys (for i18n/observability) and resolve user-facing text via localization layers.

When returning an error from a function, include contextual information. Use `fmt.Errorf` with `%w` (or similar error wrapping) to add a message while preserving the original error.