# 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.