From 158a82447bcc62f6d268f7e66b4b0c532642662c Mon Sep 17 00:00:00 2001 From: Chase Granberry Date: Tue, 17 Oct 2023 15:59:41 -0700 Subject: [PATCH 1/2] docs: more docs --- .../{connecting.md => connecting/overview.md} | 0 docs/connecting/pool_modes.md | 21 +++++++++++++ docs/development/docs.md | 19 ++++++++++++ docs/{ => monitoring}/metrics.md | 31 +++++++++++++------ docs/orms/prisma.md | 17 ++++++++++ mkdocs.yaml | 10 ++++-- 6 files changed, 87 insertions(+), 11 deletions(-) rename docs/{connecting.md => connecting/overview.md} (100%) create mode 100644 docs/connecting/pool_modes.md create mode 100644 docs/development/docs.md rename docs/{ => monitoring}/metrics.md (80%) create mode 100644 docs/orms/prisma.md diff --git a/docs/connecting.md b/docs/connecting/overview.md similarity index 100% rename from docs/connecting.md rename to docs/connecting/overview.md diff --git a/docs/connecting/pool_modes.md b/docs/connecting/pool_modes.md new file mode 100644 index 00000000..a7a9255c --- /dev/null +++ b/docs/connecting/pool_modes.md @@ -0,0 +1,21 @@ +Configure the `mode_type` on the `user` to set how Supavisor connection pools will behave. + +The `mode_type` can be one of: + +- `transaction` +- `session` +- `native` + +## Transaction Mode + +`transaction` mode assigns a connection to a client for the duration of a single transaction. + +## Session Mode + +`session` mode assigns a connection to a client for the duration of the client connection. + +## Native Mode + +`native` mode proxies a client to the database as if it was directly connected. + +This mode is typically needed to run migrations. diff --git a/docs/development/docs.md b/docs/development/docs.md new file mode 100644 index 00000000..a3c665b4 --- /dev/null +++ b/docs/development/docs.md @@ -0,0 +1,19 @@ +Documentation is managed with [mkdocs](https://www.mkdocs.org/). + +## Adding documentation + +Edit the documentation in: + +`/docs` + +Edit the documentation nav in: + +`/mkdocs.yaml` + +Build and serve the documentation locally with: + +`mkdocs serve` + +Production documentation is built on merge into `main` with the Github Action: + +`/.github/workflows/docs.yml` diff --git a/docs/metrics.md b/docs/monitoring/metrics.md similarity index 80% rename from docs/metrics.md rename to docs/monitoring/metrics.md index 1e3c2caf..a845257d 100644 --- a/docs/metrics.md +++ b/docs/monitoring/metrics.md @@ -5,7 +5,23 @@ The metrics feature provides a range of metrics in the Prometheus format. The ma - `Supavisor.PromEx.Plugins.Tenant` - `Supavisor.Monitoring.Telem` -## Metrics exposed +## Endpoint + +To use the metrics feature, send an HTTP request to the `/metrics` endpoint. The endpoint is secured using Bearer authentication, which requires a JSON Web Token (JWT) generated using the `METRICS_JWT_SECRET` environment variable. Make sure to set this environment variable with a secure secret key. + +When a node receives a request for metrics, it polls all nodes in the cluster, accumulates their metrics, and appends service tags such as region and host. To generate a valid JWT, use a library or tool that supports JWT creation with the HS256 algorithm and the `METRICS_JWT_SECRET` as the secret key. + +Remember to keep the `METRICS_JWT_SECRET` secure and only share it with authorized personnel who require access to the metrics endpoint. + +### Filtered per tenant + +Metrics endpoints filtered for specific tenants are available at their own endpoints: + +``` +/metrics/:external_id +``` + +## System, VM & application metrics The exposed metrics include the following: @@ -17,15 +33,12 @@ The exposed metrics include the following: - CPU utilization - RAM usage - Load average (LA) + +## Tenant metrics + +Supavisor also tags many metrics with the `tenant` `external_id` so you can drill down to metrics per tenant: + - Pool checkout queue time - Number of connected clients - Query duration and query counts - Network usage for client sockets and database sockets - -## Usage - -To use the metrics feature, send an HTTP request to the `/metrics` endpoint. The endpoint is secured using Bearer authentication, which requires a JSON Web Token (JWT) generated using the `METRICS_JWT_SECRET` environment variable. Make sure to set this environment variable with a secure secret key. - -When a node receives a request for metrics, it polls all nodes in the cluster, accumulates their metrics, and appends service tags such as region and host. To generate a valid JWT, use a library or tool that supports JWT creation with the HS256 algorithm and the `METRICS_JWT_SECRET` as the secret key. - -Remember to keep the `METRICS_JWT_SECRET` secure and only share it with authorized personnel who require access to the metrics endpoint. diff --git a/docs/orms/prisma.md b/docs/orms/prisma.md new file mode 100644 index 00000000..a959bc14 --- /dev/null +++ b/docs/orms/prisma.md @@ -0,0 +1,17 @@ +Connecting to a Postgres database with Prisma is easy. + +## PgBouncer Compatability + +Supavisor pool modes behave the same way as PgBouncer. You should be able to connect to Supavisor with the exact same connection string as you use for PgBouncer. + +## Named Prepared Statements + +Prisma will use named prepared statements to query Postgres by default. + +To turn off named prepared statements use `pgbouncer=true` in your connection string with Prisma. + +The `pgbouncer=true` connection string parameter is compatable with Supavisor. + +## Prisma Connection Management + +Make sure to review the [Prisma connection management guide](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management). diff --git a/mkdocs.yaml b/mkdocs.yaml index a2d96117..1f044d33 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -10,10 +10,16 @@ nav: - Development: - Installation: 'development/installation.md' - Setup: 'development/setup.md' + - Docs: 'development/docs.md' - Deployment: - Deploy with Fly.io: 'deployment/fly.md' - - Connecting: 'connecting.md' - - Metrics: 'metrics.md' + - Connecting: + - Overview: 'connecting/overview.md' + - Pool Modes: 'connecting/pool_modes.md' + - Monitoring: + - Metrics: 'monitoring/metrics.md' + - ORMs: + - Prisma: 'orms/prisma.md' theme: name: 'material' From 62704912313e5189d46ae46120c1f081b9a7b038 Mon Sep 17 00:00:00 2001 From: Chase Granberry Date: Thu, 19 Oct 2023 13:03:23 -0700 Subject: [PATCH 2/2] fix: version --- VERSION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION b/VERSION index 5d11b147..7a50b681 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.9.15 +0.9.18