Metrics

GET /metrics (superuser-only) exposes a standard Prometheus exposition response, one series per registered workspace — a bucket that exists in S3 but was never registered simply doesn’t appear:

Metric	Labels	Meaning
atlas_users	—	Registered, non-revoked principals.
atlas_documents	workspace	Indexed documents.
atlas_documents_size_bytes	workspace	Total size of indexed documents.
atlas_orphan_documents	workspace	Indexed documents whose source object is gone.
atlas_stale_documents	workspace	Indexed documents whose source object changed since declaration.
atlas_bucket_objects	workspace	S3 object versions on record for the bucket.
atlas_bucket_size_bytes	workspace	Total size of S3 object versions on record for the bucket.

Every number is recomputed straight from Postgres on each scrape rather than tracked incrementally — the same instinct behind S3 being the source of truth for what exists applies here too: a value that’s only ever updated on write can quietly go stale (a deleted workspace’s last-known figure lingering forever, say), while one recomputed from source on every scrape simply can’t.

There’s also deliberately no “all workspaces” series alongside the per-workspace ones — sum(atlas_documents) in PromQL or Grafana already answers that, and a second, Atlas-computed global figure would risk quietly disagreeing with it (over a bucket that exists in S3 but was never registered, for instance). Aggregation is left to the query layer that’s already good at it.

Point Prometheus at the endpoint with credentials that can authenticate as a superuser — a dedicated API key is the natural fit:

scrape_configs:
  - job_name: atlas
    metrics_path: /api/v1/metrics
    authorization:
      credentials: atlas_...
    static_configs:
      - targets: ["atlas-api:8000"]