calendar-plugin/requirements/observability.md

Observability Requirements

Purpose

Define logging, auditability, and operational visibility requirements for calendar, user access, API, CalDAV, and ICS behavior.

Scope

This document covers:

• Operational logs
• Audit logs for privileged actions
• Metrics and health signals
• Retention and privacy controls

Logging Principles

• Logs must support troubleshooting and security review.
• Log format should be structured where practical.
• Sensitive values must be redacted.
• Payload capture should be bounded and summarized to avoid oversized/noisy traces (for example large HTML responses).

Required Operational Logs

Must log:

• Plugin startup/activation and migration outcomes
• API/CalDAV/ICS request summaries with status and latency
• Error events (5xx, auth failures, precondition conflicts where relevant)
• Email workflow outcomes (verification/reset/admin-approval notifications)

Recommended fields:

• timestamp
• request id/correlation id
• actor type/id (if available)
• endpoint/action
• status code/outcome
• latency

Required Audit Logs

Must audit:

• Event create/update/delete actions from admin/API
• Single-occurrence delete/edit exception actions
• CalDAV user state transitions (pending_approval, active)
• Admin approval/removal actions for CalDAV users
• Setup/configuration changes

Audit entry minimum fields:

• actor identity
• action
• target identity
• prior state (where applicable)
• resulting state
• timestamp

Health and Metrics

At minimum expose/log:

• request counts by surface (admin/api/caldav/ics)
• error rates by category
• average and p95 latency for key endpoints
• queue/dispatch failures for email workflows

Retention and Access

• Log retention duration must be documented in operational docs.
• Access to detailed logs should be restricted to authorized operators/admins.
• Audit logs should be tamper-evident by process and protected from casual deletion.
• Fixture admin diagnostics UI may expose only a recent bounded window (for example last 20 entries) for quick troubleshooting.

Privacy and Compliance

• Do not log passwords, token raw values, or full credential headers.
• PII in logs should be minimized to necessary operational scope.

Verification Requirements

Acceptance should verify:

• Required events produce expected logs/audit records.
• Security-sensitive data is redacted.
• Operators can trace a failed user flow end-to-end using request/audit identifiers.