79 lines
2.4 KiB
Markdown
79 lines
2.4 KiB
Markdown
# 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.
|