PHI-Safe Error Logging and Support Diagnostics for AFH Software

Adult family home software needs enough diagnostic evidence to explain failed medication submissions, stuck reports, pharmacy sync errors, and sign-in problems without copying resident names, directions, documents, tokens, or incident narratives into general-purpose logs. Good observability preserves technical context while keeping sensitive care content inside protected systems.

This guide covers application logging and support design, not a determination that every AFH or software vendor is subject to the same federal rules. It was reviewed on August 8, 2026. Organizations should apply current privacy, security, contractual, retention, and incident-response requirements to their environment.

Separate record audit history from technical logs

Resident record audit history should answer who viewed, created, changed, amended, exported, or deleted a protected record. Technical logs should explain application and infrastructure behavior.

Do not use one store for both. A MAR amendment needs durable resident-record context; a database timeout log needs service, operation, correlation ID, and error class.

Keep links through opaque event identifiers so authorized investigators can correlate them without placing the resident payload in the logging platform.

Build an explicit logging data classification

Classify fields before instrumenting:

• Safe operational metadata
• Pseudonymous identifiers
• Sensitive personal or facility data
• Resident health or care content
• Authentication secrets and tokens
• Cryptographic keys and credentials
• Payment data
• Uploaded file content

Define permitted destinations and retention for each class. Default application loggers should accept only approved structured fields.

The OWASP Logging Cheat Sheet advises excluding or masking session values, access tokens, sensitive personal data, passwords, connection strings, encryption keys, and information above the logging system's classification.

Use structured events

Each diagnostic event can include:

• Event type and severity
• Application, environment, and build
• Service and operation
• Correlation and request IDs
• Pseudonymous user, facility, and resource references
• Start, duration, and outcome
• Error class and stable code
• Dependency and retry state
• Feature or schema version
• Device and browser family at a coarse level

Avoid arbitrary message strings containing serialized requests. Structured allowlisted fields are easier to filter, redact, retain, and audit.

Keep request and response bodies out by default

Medication orders, daily notes, incidents, documents, contact details, and pharmacy messages can contain sensitive information. Do not log full request bodies, response bodies, GraphQL variables, form state, or document URLs automatically.

When troubleshooting needs a field-level clue, log the schema field name, validation code, data type, and whether a value was present—not the actual value.

For example, record startdateafterenddate rather than both resident order dates and medication details.

Scrub URLs and headers

Remove query strings and fragments unless individual parameters are explicitly approved. Tokens, invitation codes, resident IDs, report filters, and signed file credentials often appear there.

Never log Authorization, Cookie, Set-Cookie, API key, or signed URL values. Sanitize Referer and location fields.

Use generated route names such as /app/residents/:residentId rather than storing the actual path. Validate and encode log fields to prevent newline or delimiter injection.

Pseudonymize identifiers consistently

Support correlation can use keyed hashes or protected opaque IDs rather than names and emails. Choose a rotation and scope policy that balances investigation with privacy.

Do not use a plain hash of a predictable resident ID if it can be reversed by enumeration. Keep mapping access inside the protected application and restrict who can resolve it.

Use different identifiers for analytics when cross-system linking is unnecessary. A broad universal pseudonym can become sensitive through aggregation.

Capture medication failures safely

For a failed medication action, log:

• Operation: create order, accept, schedule, administer, amend, refill, or receive
• Opaque facility, resident, order, and opportunity references
• Auth decision code
• Schema and rule version
• Validation error codes
• Idempotency key hash
• Source channel such as facility or pharmacy
• Retry and sync state
• Final technical outcome

Do not log medication name, dosage, directions, diagnosis, prescriber, resident name, or note text in the central error event.

Authorized support can open a protected correlation view after approval when the actual record is necessary.

Design controlled diagnostic escalation

When ordinary telemetry is insufficient, use a time-bounded diagnostic mode scoped to a facility, user, device, or operation. Require an authorized support case, approver, reason, fields enabled, start, expiration, and review.

Do not offer “log everything.” Additional diagnostics should still redact secrets and care content. Notify the tenant or record access according to policy.

Expire the mode automatically and purge temporary detail under its shorter lifecycle.

Build a safe support bundle

Let an authorized user generate a bundle containing:

• Build and service-worker versions
• Browser and operating-system family
• Feature flags relevant to the issue
• Recent stable error codes
• Queue and sync state
• Connection and storage diagnostics
• Redacted correlation IDs
• User-provided issue description

Preview the bundle before submission and identify what it excludes. Never attach resident exports, screenshots, or local databases automatically.

The service-worker update safety guide explains version and cache diagnostics for flicker, stale assets, and update failures.

Protect screenshots and recordings

Screenshots may reveal resident names, medication lists, documents, emails, and browser tabs. Treat them as protected support attachments with private storage, limited access, retention, and audit.

Provide a built-in redaction tool or clear instructions. For session replay, mask input and sensitive text by default, block protected routes where masking cannot be proven, and never capture passwords or tokens.

Do not send support attachments into public issue trackers or unrestricted chat channels.

Control third-party telemetry

Inventory every error, analytics, performance, chat, and replay provider. Document data fields, regions, retention, subprocessors, access, contracts, and deletion behavior.

Apply server-side filtering before transmission when possible. Client configuration alone can fail during an exception path.

Use separate projects for production and nonproduction. Never seed production resident data into a development telemetry project.

Make logs tenant-aware without exposing tenants

Include a protected tenant reference on each operational event so teams can identify whether an incident affects one facility or the platform. Restrict tenant-resolution access.

Tenant scope also prevents support staff from searching all facilities by resident name. Diagnostic queries should begin with case and authorized facility.

Alert on conflicting tenant and resource identifiers, but store only opaque references in the central signal.

Protect integrity and access

Centralize logs with encrypted transport, restricted write paths, role-based read access, tamper detection, retention locks where appropriate, and monitored administrative actions.

Record who searched, exported, changed retention, enabled diagnostic mode, or accessed a protected correlation view. Support and engineering roles do not automatically need the same detail.

Maintain enough availability to investigate incidents, but cap event size and rate so an attacker cannot exhaust storage through log flooding.

Define retention and disposal

Use different retention for security events, application errors, performance metrics, temporary diagnostics, and support attachments. Base periods on operational need and applicable obligations.

Do not retain debug payloads indefinitely “just in case.” Verify deletion in primary stores, archives, exports, and provider systems.

Legal hold or incident preservation must be explicit, scoped, and auditable. It should not turn every log into permanent resident data.

Detect when logging fails

Monitor event throughput, expected heartbeats, ingestion delay, rejected oversized events, redaction failures, schema errors, storage capacity, and exporter health.

If the redaction layer fails closed, retain a minimal local counter and alert without sending the unsafe payload. Do not bypass scrubbing to keep the dashboard green.

Reconcile critical application actions against their resident audit trail so missing technical logs are visible without using logs as the record of care.

Test leak and diagnostic cases

Use synthetic data to verify:

1. Medication validation error logs no entered values.
2. Resident ID in URL becomes a route placeholder.
3. Authorization and cookie headers are removed.
4. Invitation token never reaches logs.
5. Signed document URL is scrubbed.
6. Newline and delimiter injection is encoded.
7. Browser exception does not serialize form state.
8. Support bundle previews only approved fields.
9. Screenshot is stored as protected attachment.
10. Diagnostic mode expires automatically.
11. Tenant resolver requires an approved case.
12. Third-party project receives only allowlisted fields.
13. Revoked support user loses log access.
14. Logging outage triggers a heartbeat alert.
15. Retention deletion reaches archives.
16. Cross-facility correlation search is denied.

Scan emitted telemetry for synthetic names, medications, directions, emails, tokens, and document values after each test.

Frequently asked questions

Should error logs include the request body?

Not by default. Record operation, schema, error code, presence, and opaque correlation IDs; inspect protected records through an authorized workflow only when necessary.

Are hashed resident IDs automatically safe?

No. Predictable identifiers can be enumerated, and consistent pseudonyms can become sensitive. Use keyed or opaque references with restricted resolution.

Can support ask for a screenshot?

Yes through a protected, authorized attachment workflow with redaction, limited access, retention, and audit—not a public channel.

What if redaction fails?

Fail closed for the unsafe event, record a minimal safe counter, and alert the telemetry owner. Do not transmit the raw payload.

Are application logs the resident audit trail?

No. Keep durable record access and change history inside the protected application domain and use opaque links for technical correlation.

Diagnose failures without duplicating resident records

PHI-safe observability classifies data, uses structured allowlists, strips bodies and secrets, pseudonymizes identifiers, controls diagnostic escalation, protects support files, and monitors its own integrity.

Explore AFH Manager to test redacted error events, protected correlation, support bundles, diagnostic expiration, tenant-scoped access, and telemetry leak checks with synthetic residents.