Skip to content

About

Community-maintained observability for self-hosted Supabase: logs, metrics, and traces.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

0 watching

Forks

Supabase Observability

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.

Why this exists

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.

Status

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

How it runs

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.

Replaceable backends

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.

Support

Community-maintained, and separate from Supabase's official support. Please open issues on this repository rather than the Supabase repositories.

Contributing

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.

License

Apache 2.0

About

Community-maintained observability for self-hosted Supabase: logs, metrics, and traces.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages