diff --git a/apps/docs/content/guides/telemetry/metrics.mdx b/apps/docs/content/guides/telemetry/metrics.mdx index ced0f742077..0309a85ab88 100644 --- a/apps/docs/content/guides/telemetry/metrics.mdx +++ b/apps/docs/content/guides/telemetry/metrics.mdx @@ -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://.supabase > curl https://.supabase.co/customer/v1/privileged/metrics --user 'service_role:' ``` -## 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. - - 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. + + + 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. - -Prerequisites: - -- Must have [Docker](https://www.docker.com/products/docker-desktop/) or a Docker compatible runtime on your machine - - - -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. - - - - - - - - - Download the code from the [GitHub repo](https://github.com/supabase/supabase-grafana/tree/main) - - - - - ```sh - git clone https://github.com/supabase/supabase-grafana.git - ``` - - - - - - - - copy the `example.env` into a new `.env` - - - - ```sh - cp .env.example .env - ``` - - - - - - - - - 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. - - - - - - - - - - Add the values to your `.env` file: - ```text .env - SUPABASE_PROJECT_REF="your_project_reference" - SUPABASE_SERVICE_ROLE_KEY="your_service_role" - ``` - - - - - ```text .env - SUPABASE_ACCESS_TOKEN="your_access_token" - ``` - - - - - - - - - For security, consider using a [password generator](https://bitwarden.com/password-generator/) - - - - - ```text .env - GRAFANA_PASSWORD="your password" - ``` - - - - - - - - Deploy the server. Once it is active, you can go to localhost:8000/login in the browser - - - - ```text - docker compose up - ``` - - - - - - - Login with your username (default is `admin`) and the password you created in step 4. - - - ![Grafana login](/docs/img/guides/platform/grafana-login.png) - - - - - -### Deploying to Grafana cloud - - - This section describes the Grafana cloud Supabase template, which is created and maintained by - Grafana. - - - - - - - - Go to Grafana\'s [registration form](https://grafana.com/auth/sign-up/create-user?pg=login) and create an account - - - ![Grafana Registration Page](/docs/img/guides/platform/grafana-registration.png) - - - - - - - - Grafana will prompt you to create a stack. Give it a name and continue. - - - ![Create Grafana Stack](/docs/img/guides/platform/create-grafana-stack.png) - - - - - - - - Create a new Dashboard - - - ![Select Grafana Dashboard](/docs/img/guides/platform/select-grafana-dashboard.png) - - - - - - - - - ![Select Grafana Dashboard](/docs/img/guides/platform/supabase-grafana-template.png) - - - - - - - - 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. - - - ![Add credentials](/docs/img/guides/platform/add-credentials-grafana.png) - - - - - diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml index 671d1f4461b..eb261d1af02 100644 --- a/supa-mdx-lint/Rule003Spelling.toml +++ b/supa-mdx-lint/Rule003Spelling.toml @@ -309,6 +309,7 @@ allow_list = [ "supabase-community", "supabase-flutter", "supabase-gdscript", + "supabase-grafana", "supabase-go", "supabase-js", "supabase-kt",