dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update metrics documentation (#33893)

Browse Source 
* add genera deployment instructions for both grafana and prometheus

* add supabase-grafana to spellchecks
This commit is contained in:
Chris Gwilliams authored and GitHub committed 2025-03-03 14:03:29 +02:00
1 parent eca4cc15a2
commit d55f6fb780
2 files changed
+64 -193
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/docs/content/guides/telemetry/metrics.mdx
+63 -193
View File
@@ -4,7 +4,7 @@ title: 'Metrics'
description: 'Observability for your Supabase project'
---
In addition to the reports and charts built in to the Supabase dashboard, each project hosted on the Supabase platform comes with a [Prometheus](https://prometheus.io/)-compatible metrics endpoint, which can be used to gather insight into the health and status of your project.
In addition to the reports and charts built in to the Supabase dashboard, each project hosted on the Supabase platform comes with a [Prometheus](https://prometheus.io/)-compatible metrics endpoint, updated every minute, which can be used to gather insight into the health and status of your project.
You can use this endpoint to ingest data into your own monitoring and alerting infrastructure, as long as it is capable of scraping Prometheus-compatible endpoints, in order to set up custom rules beyond those supported by the Supabase dashboard.
@@ -28,13 +28,40 @@ Your project's metrics endpoint is accessible at `https://<project-ref>.supabase
> curl https://<project-ref>.supabase.co/customer/v1/privileged/metrics --user 'service_role:<service-role-jwt>'
```
## Configuring Prometheus
## Supabase Grafana
For self-hosted Prometheus, modify your `prometheus.yaml` file to add a Supabase job, and set the `metrics_path`, `scheme`, `basic_auth` and `targets` parameters. For example:
The pre-configured Supabase Grafana Dashboard is an advanced version of the [Dashboard's Database Reports](https://supabase.com/dashboard/project/_/reports/database). It visualizes over 200 database performance and health metrics.
![Supabase Grafana](/docs/img/guides/platform/supabase-grafana-prometheus.png)
Instructions are included in the README for deploying the repository using docker.
## Using the metrics endpoint in production
To set up monitoring for your project, you will need two things:
1. A datastore - a place to store the metrics coming from your Supabase project over time
2. A dashboard - a place to visualize the state of your Supabase project for a defined period
### Setting up a metrics datastore
One of the more well-known options is [Prometheus](https://prometheus.io/docs/introduction/overview/) and it is the tool used in this guide.
You can [self-host](https://prometheus.io/docs/prometheus/latest/installation/) Prometheus or choose a managed service to store your metrics. Some of the providers offering managed Prometheus are:
- [Digital Ocean](https://marketplace.digitalocean.com/apps/prometheus)
- [AWS](https://aws.amazon.com/prometheus/)
- [Grafana Cloud](https://grafana.com/products/cloud/metrics/)
Follow the guides for the deployment option you choose
#### Adding a scrape job to Prometheus
For Prometheus, modify your `prometheus.yaml` file to add a Supabase job, and set the `metrics_path`, `scheme`, `basic_auth` and `targets` parameters. For example:
```yaml
scrape_configs:
- job_name: "MyJob"
- job_name: "MySupabaseJob"
metrics_path: "/customer/v1/privileged/metrics"
scheme: https
basic_auth:
@@ -48,198 +75,41 @@ scrape_configs:
group: "MyGroupLabel"
```
Additionally, we [maintain a repo](https://github.com/supabase/supabase-grafana) for a scraping agent to work with Grafana Cloud.
### Setting up a dashboard
## Deploying Supabase Grafana
For this guide, we will be using [Grafana](https://grafana.com/docs/grafana/latest/introduction/).
The pre-configured Supabase Grafana Dashboard is an advanced version of the [Dashboard's Database Reports](https://supabase.com/dashboard/project/_/reports/database). It visualizes over 200 database performance and health metrics and is updated every minute.
You can [self-host](https://grafana.com/docs/grafana/latest/setup-grafana/installation/) Grafana or many providers offer managed Grafana, some of which are listed below:
![Supabase Grafana](/docs/img/guides/platform/supabase-grafana-prometheus.png)
- [DigitalOcean](https://marketplace.digitalocean.com/apps/grafana)
- [AWS](https://aws.amazon.com/grafana/)
- [Grafana Cloud](https://grafana.com/grafana/)
### Deploying locally
Follow the guides of the provider you choose to get Grafana up and running.
<Admonition type="note">
This method uses docker to deploy locally but the same steps can be used to deploy to a dedicated
server, such as [Fly](https://fly.io), [Railway](https://railway.app) or [Digital
Ocean](https://digitalocean.com)
### Adding a data source to Grafana
In the left-hand menu, select `Data sources` and click `Add new data source`.
Select `Prometheus` and enter the connection details for the Prometheus instance you have set up.
Under **Interval behavior**, set the **scraping interval** to 60s and test the data source. Once it has passed, save it.
### Adding the Supabase dashboard
In the left-hand menu, select `Dashboards` and click `New`. From the drop-down, select `Import`.
Copy the raw file from our [supabase-grafana](https://raw.githubusercontent.com/supabase/supabase-grafana/refs/heads/main/grafana/dashboard.json) repository and paste it (or upload the file).
Click `Load` and the dashboard will load from the project specified in your Prometheus job.
### Monitoring your project
You can configure alerts from Prometheus or Grafana. The `supabase-grafana` repository has a selection of [example alerts](https://github.com/supabase/supabase-grafana/blob/main/docs/example-alerts.md) that can be configured.
<Admonition type="caution">
Grafana Cloud has an unofficial integration for scraping Supabase metrics. See their
[docs](https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-supabase/)
for instructions on how to configure it but note that it is not full-featured nor is it supported
by Supabase.
</Admonition>
Prerequisites:
- Must have [Docker](https://www.docker.com/products/docker-desktop/) or a Docker compatible runtime on your machine
<Admonition type="note">
Supabase Grafana only tracks metrics while it's active. For monitoring historical trends, it's better to use a dedicated server that can record data continuously.
</Admonition>
<StepHikeCompact>
<StepHikeCompact.Step step={1} >
<StepHikeCompact.Details title="Download the project">
Download the code from the [GitHub repo](https://github.com/supabase/supabase-grafana/tree/main)
</StepHikeCompact.Details>
<StepHikeCompact.Code>
```sh
git clone https://github.com/supabase/supabase-grafana.git
```
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2} >
<StepHikeCompact.Details title="Create a .env file">
copy the `example.env` into a new `.env`
</StepHikeCompact.Details>
<StepHikeCompact.Code>
```sh
cp .env.example .env
```
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3}>
<StepHikeCompact.Details title="Add your credentials">
- To monitor a single project, add your service_role key from the [API Settings](https://supabase.com/dashboard/project/_/settings/api) and Project ID from the [General Settings](https://supabase.com/dashboard/project/_/settings/general).
- To monitor multiple projects, create an [account access token](https://supabase.com/dashboard/account/tokens) and add it to your `.env` file.
</StepHikeCompact.Details>
<StepHikeCompact.Code>
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="single-project"
>
<TabPanel id="single-project" label="Monitor a single project">
- Add the values to your `.env` file:
```text .env
SUPABASE_PROJECT_REF="your_project_reference"
SUPABASE_SERVICE_ROLE_KEY="your_service_role"
```
</TabPanel>
<TabPanel id="monitor-an-org" label="monitor multiple projects">
```text .env
SUPABASE_ACCESS_TOKEN="your_access_token"
```
</TabPanel>
</Tabs>
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={4}>
<StepHikeCompact.Details title="Add a password to your .env">
<Admonition type="note" label="password manager">
For security, consider using a [password generator](https://bitwarden.com/password-generator/)
</Admonition>
</StepHikeCompact.Details>
<StepHikeCompact.Code>
```text .env
GRAFANA_PASSWORD="your password"
```
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={5}>
<StepHikeCompact.Details title="Deploy Grafana with Docker">
Deploy the server. Once it is active, you can go to <a href='http://localhost:8000/login'>localhost:8000/login</a> in the browser
</StepHikeCompact.Details>
<StepHikeCompact.Code>
```text
docker compose up
```
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={6}>
<StepHikeCompact.Details title="Login" >
Login with your username (default is `admin`) and the password you created in step 4.
</StepHikeCompact.Details>
<StepHikeCompact.Code>
![Grafana login](/docs/img/guides/platform/grafana-login.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
</StepHikeCompact>
### Deploying to Grafana cloud
<Admonition type="note">
This section describes the Grafana cloud Supabase template, which is created and maintained by
Grafana.
</Admonition>
<StepHikeCompact>
<StepHikeCompact.Step step={1}>
<StepHikeCompact.Details title="Create a free Grafana Cloud account" >
Go to Grafana\'s [registration form](https://grafana.com/auth/sign-up/create-user?pg=login) and create an account
</StepHikeCompact.Details>
<StepHikeCompact.Code>
![Grafana Registration Page](/docs/img/guides/platform/grafana-registration.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={2} >
<StepHikeCompact.Details title="Give a name to your Grafana project">
Grafana will prompt you to create a stack. Give it a name and continue.
</StepHikeCompact.Details>
<StepHikeCompact.Code>
![Create Grafana Stack](/docs/img/guides/platform/create-grafana-stack.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={3} >
<StepHikeCompact.Details title="Create a new Grafana Dashboard">
Create a new Dashboard
</StepHikeCompact.Details>
<StepHikeCompact.Code>
![Select Grafana Dashboard](/docs/img/guides/platform/select-grafana-dashboard.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={4} >
<StepHikeCompact.Details title="Search for the Supabase template" />
<StepHikeCompact.Code>
![Select Grafana Dashboard](/docs/img/guides/platform/supabase-grafana-template.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
<StepHikeCompact.Step step={5} >
<StepHikeCompact.Details title="Add your credentials and deploy">
Add your service_role key from the [API Settings](https://supabase.com/dashboard/project/_/settings/api) and Project ID from the [General Settings](https://supabase.com/dashboard/project/_/settings/general) to your Grafana credentials. Then install your dashboard.
</StepHikeCompact.Details>
<StepHikeCompact.Code>
![Add credentials](/docs/img/guides/platform/add-credentials-grafana.png)
</StepHikeCompact.Code>
</StepHikeCompact.Step>
</StepHikeCompact>
supa-mdx-lint/Rule003Spelling.toml
+1
View File
@@ -309,6 +309,7 @@ allow_list = [
"supabase-community",
"supabase-flutter",
"supabase-gdscript",
"supabase-grafana",
"supabase-go",
"supabase-js",
"supabase-kt",