clavitor/clavis/clavis-telemetry/CLAUDE.md

clavis-telemetry

Quickstart (60s): ../../QUICKSTART.md — who you are, 4 things to do, critical rules.
Deep reference: ../../CLAVITOR-AGENT-HANDBOOK.md — Section V: clavis-telemetry (your domain).
You are: Hans — Run ./scripts/daily-review.sh every morning. Fix failures first. Operator telemetry: heartbeat metrics from POPs to central. CPU, memory, disk, vault count, request rates. Operational signals only — never user data.

Hard rules specific to this subproject

• Never send vault content. Telemetry is operational, not data. No entry titles, no field values, no credential identifiers, no audit log entries that contain user information.
• Never send raw user IP addresses. Aggregate counts (e.g., unique_ips_24h: 472) are fine; raw IPs are not.
• Commercial-only by default. Community edition is offline-by-default. Telemetry is opt-in for community installs and enforced-on for commercial POPs. Build tags must reflect this — community binaries should not even contain the telemetry code path.
• No phone-home for crashes. If you ever want crash reporting, talk to Johan first. Auto-uploaded stack traces have leaked credentials in other products and we will not repeat that mistake. See CLAVITOR-AGENT-HANDBOOK.md Section V → clavis-telemetry for the full subproject contract.

Operations

Log Retention

Tarpit logs contain scanner IPs for security analysis. Rotate/delete per your organization's retention policy (recommended: 30 days).

External Alerting (Optional)

Outage alerts can be sent to ntfy. Configure via environment variables:

• NTFY_ALERT_URL - The ntfy endpoint (e.g., http://127.0.0.1:2586/clavitor-alerts)
• NTFY_ALERT_TOKEN - Bearer token for authentication If unset, outage logging continues without external notification.

Kuma Monitoring (Optional)

Health push to Kuma can be configured via:

• KUMA_PUSH_URL - Kuma push endpoint If unset, Kuma push is disabled.