Observability & Logging 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.