PlanetScale
Connect a PlanetScale organization to Maple. Maple discovers every database branch's metrics endpoint, scrapes connections, WAL size, and pod CPU, and adds your databases to the service map.
PlanetScale publishes Prometheus metrics per database branch behind a service-discovery API. One organization endpoint returns the current list of branch metrics targets, and that list changes as branches are created and deleted. You connect the organization once. Maple runs the discovery call, scrapes every branch it returns, and refreshes the branch list every 10 minutes.
Setup has two parts. An OAuth authorization covers the management plane: database inventory, query insights, and webhooks. PlanetScale serves branch metrics only to service tokens, so you add a service token to turn on metrics.
Prerequisites
- Permission in the PlanetScale organization to authorize an OAuth application and create a service token.
1. Authorize Maple
Open Integrations → PlanetScale in Maple and click Connect PlanetScale. A popup takes you to PlanetScale to authorize Maple’s OAuth application. You can revoke access from PlanetScale at any time.
- If the authorization covers one organization, Maple binds it automatically.
- If it covers several, pick one. You can also set Only these branches (optional) and Exclude branches (optional). Both take glob patterns, where
*matches any run of characters and?matches exactly one (for examplepr-*, preview-*).
To switch organizations later, click Change organization.
The OAuth application needs read_databases for the database inventory, the service map, and query insights. If it is missing, the Permissions step shows Reauthorize with read_databases.
2. Add a service token for branch metrics
After authorization the card shows a four-step checklist: Authorization, Permissions, Branch metrics access, and Metrics arriving. The Branch metrics access step asks for a service token. If the OAuth authorization already covers the metrics endpoints, this step completes without one.
- Click Create a token in PlanetScale. Create a service token with the
read_metrics_endpointsorganization permission. No other permission is needed. - Paste the Service token ID and Service token secret into Maple.
- Click Enable metrics.
The secret is encrypted at rest. Maple derives the discovery URL (https://api.planetscale.com/v1/organizations/{org}/metrics), authenticates discovery and every scrape with the token, and scrapes each branch as its own target. New branches are picked up on the next discovery refresh. Deleted branches stop being scraped.
To replace the token later, click Rotate token.
3. Optional: webhooks
Under Webhooks, click Show setup to reveal an endpoint URL and signing secret. Register them in each database’s webhook settings on PlanetScale. Only Maple organization admins can view the secret.
Verify
- The Metrics arriving step changes from Waiting for the first scrape. to done, and the checklist collapses to a single health row reading Streaming branch metrics from your organization. The card polls while it waits, so you do not need to reload.
- Open Infrastructure → PlanetScale to see your databases and branches.
- In the metrics explorer, search for
planetscale_to see branch series.
What you get
Each branch series carries PlanetScale’s discovery labels. The most useful is planetscale_database_branch_id, which keys every series to a branch. Highlights from the metric set (Postgres, Vitess):
| Metric | What it tells you |
|---|---|
planetscale_postgres_connection_state | Connections by state (active, idle, idle in transaction). |
planetscale_edge_postgres_active_connections | Active connections at the edge. |
planetscale_postgres_wal_size_bytes | WAL size. An early warning for replication and disk usage. |
planetscale_pgbouncer_current_connections | PgBouncer pool utilization. |
planetscale_pods_cpu_util_percentages | CPU per pod backing the branch. |
planetscale_vtgate_total_pods | (Vitess) vtgate pods per availability zone. |
Group dashboards and alert rules by planetscale_database_branch_id. For example, alert when WAL size passes a threshold or active connections approach your pool limit.
Troubleshooting
- Metrics arriving shows “The last scrape failed.” The health row shows the error. A failure for one branch is prefixed with
[branch:<id>]. - 401 or 403 on discovery or scrapes. The service token was deleted or lacks
read_metrics_endpoints. Click Rotate token and paste a new one. - Authorization shows as revoked. Click Reconnect to authorize again.
- Metrics stopped arriving. The Metrics arriving step reports a stall after three scrape intervals without data. Check the error on the health row.
- A discovery call fails. Maple keeps scraping the last known branch list and shows the discovery error on the target, so branch metrics do not drop out during a PlanetScale API outage.
- Branch filters did not apply. Changes take effect on the next scrape because the cached branch list is cleared on save.
Next steps
- Service map: PlanetScale databases linked to the services that query them.
- Prometheus scraping: how scraped samples become OpenTelemetry metrics.
- Alert rules: alert on branch metrics.