Skip to content
CompassDocsCompassDocs

Monitoring & Health

CompassDocs ships with everything an on-call rotation expects: liveness and readiness probes, a Prometheus metrics endpoint, a live diagnostics panel, and an optional JSON log format. All of it is built in — no sidecar or agent required. Available from v0.65.

Health probes

Section titled “Health probes”

Two unauthenticated endpoints, each answering a different question:

Endpoint Question Healthy response
GET /healthz Is the process alive? 200 with { "status": "ok", "version": "…", "uptime_seconds": … }
GET /readyz Can it serve traffic? 200 with { "status": "ready", "db_latency_ms": … } — 503 when the database is unreachable

Point orchestrator restarts (Docker HEALTHCHECK, Kubernetes livenessProbe) at /healthz, and load-balancer routing (readiness probes, upstream checks) at /readyz. The split matters: a database blip should pull an instance out of rotation, not restart a healthy process.

# Kubernetes example
livenessProbe:
  httpGet: { path: /healthz, port: 3000 }
readinessProbe:
  httpGet: { path: /readyz, port: 3000 }

Prometheus metrics

Section titled “Prometheus metrics”

GET /metrics serves the standard exposition format:

  • Process — RSS, V8 heap, uptime, build version/Node version labels.
  • Database pool — open, idle, and waiting connection counts, plus a compassdocs_db_up gauge from the scrape itself.
  • Activity counters — sign-ins (success/failure), searches, AI requests, and audit exports since process start.
  • Workspace gauges — total/active users, documents, spaces, unexpired sessions, and audit-log size.

Scrapers authenticate with a bearer token. Set it in the environment:

Terminal window
COMPASSDOCS_METRICS_TOKEN=<long random string>
prometheus.yml
scrape_configs:
  - job_name: compassdocs
    metrics_path: /metrics
    authorization:
      credentials: <the same token>
    static_configs:
      - targets: ["docs.example.com"]
    scheme: https

A signed-in admin can always open /metrics in a browser, token or not. With no token configured, that’s the only way in — the endpoint never serves anonymous requests.

Diagnostics panel

Section titled “Diagnostics panel”

Settings → System includes a Diagnostics card that live-checks each subsystem the install depends on — database round-trip, upload-directory writability, SMTP configuration, AI provider, semantic search/pgvector, the license, and the metrics endpoint — each with a pass / attention / failing status and a plain-language explanation. Use Run checks after any infrastructure change to confirm everything still holds together.

Structured logging

Section titled “Structured logging”

By default, operational events print as readable console lines. For log shippers (Loki, CloudWatch, Datadog, …), switch to JSON lines:

Terminal window
COMPASSDOCS_LOG_FORMAT=json

Each event becomes a single JSON object with ts, level, event, and event-specific fields — e.g. a failed readiness check logs {"ts":"…","level":"error","event":"readyz.db_unreachable","error":"…"}.

Housekeeping

Section titled “Housekeeping”

The app runs its own hourly maintenance (no external cron needed): expired sessions and used OAuth codes are purged so hot tables stay small, alongside the existing scheduled backups, review reminders, and digests. There is nothing to configure.

CompassDocs service status