Community-maintained observability for self-hosted Supabase. Logs and metrics collected into open-source backends, with Grafana dashboards. Traces are planned - see Status for what ships today.
For anything about Supabase itself, see the official documentation.
Supabase Cloud has a strong observability story: a Metrics API, a Logs Explorer, and Log Drains. Self-hosting trades those for control over your own infrastructure. This project brings logs and metrics back with open-source components you run yourself.
| Signal | State | Default components |
|---|---|---|
| Logs | Available | Vector into VictoriaLogs, or Loki |
| Metrics | Available | OpenTelemetry Collector into VictoriaMetrics |
| Traces | Planned | OpenTelemetry Collector, OTLP |
| Dashboards | Available | Grafana |
| Alerting | Planned | vmalert, Alertmanager |
| Kubernetes | Planned | Helm chart |
Start here: docs/README.md
your machine
├── supabase/docker/ your Supabase deployment
│ ├── docker-compose.yml
│ └── .env
│ └── COMPOSE_FILE metrics only
│ └── lists ─────────────────┐
│ │
└── supabase-observability/ │
├── overrides/ │
│ ├── metrics.yml ◄───────────────┤
│ └── metrics-envoy.yml ◄─────────┘
│ └── turn Supabase's metrics endpoints on
│
├── docker-compose.o11y-logs.yml
│ └── reads container logs via the Docker socket
│
├── docker-compose.o11y-metrics.yml
│ └── scrapes those endpoints
│
└── docker-compose.o11y-dashboards.yml
└── Grafana, reading both stores
supabase/docker/ is your existing Supabase deployment.
supabase-observability/ is this project.
Logs, metrics, and dashboards are each a separate Compose file inside
this repo, and each runs as its own Compose project
(supabase-observability-logs, supabase-observability-metrics, and
supabase-observability-dashboards), so you run only the ones you want.
Each Compose file reads its settings from the matching folder under
config/. Traces will add its own file when it lands, and you'll bring it
up the same way, alongside whichever ones you already have running.
Logs reads Supabase's containers from the outside and needs nothing on
Supabase's side. Metrics can't work that way: several of Supabase's
metrics endpoints are off by default or listen only inside their own
container. So you register two override files from this
repo in COMPOSE_FILE in Supabase's .env - a file Supabase's own git
ignores. This project never writes to anything under supabase/docker/
itself. See docs/metrics/README.md.
Each signal's store is chosen with one environment variable naming a
folder under config/<signal>/backends/, separate from the collection
logic itself. That folder holds everything the store needs: its
container, where the collector sends data, how Grafana connects to it, and
the store's own config.
For logs, that's BACKEND_LOGS (victorialogs or loki) - see
docs/logs/README.md. For metrics, it's
BACKEND_METRICS (victoriametrics) - see
docs/metrics/README.md.
Community-maintained, and separate from Supabase's official support. Please open issues on this repository rather than the Supabase repositories.
Fork the repository and open a pull request. See CONTRIBUTING.md for ground rules and pre-PR checks, and docs/README.md for local setup.