Send PlanetScale Metrics to SigNoz with OpenTelemetry

Overview

Configure the OpenTelemetry Collector to scrape PlanetScale's Prometheus endpoint and send branch-level database metrics to SigNoz. Use this guide for Vitess (MySQL) and Postgres database branches.

Prerequisites

A PlanetScale organization with Vitess or Postgres database branches
OpenTelemetry Collector Contrib installed
A SigNoz instance (Cloud or Self-Hosted)

Steps

Step 1: Create a PlanetScale service token

In PlanetScale, open Organization Settings > Service Tokens.
Create a service token.
Grant read_metrics_endpoints under Organization access.
Copy the service token ID and token value before closing the dialog.

Save both values in a local credentials file:

printf '%s' '<token-id>:<token>' > planetscale_token

Replace:

<token-id> with the PlanetScale service token ID
<token> with the PlanetScale service token value

The file must contain the token ID and token value separated by one colon. Do not add quotes or spaces.

For PlanetScale's token format and permissions, see the PlanetScale service token documentation.

Step 2: Configure your deployment

Choose the deployment type that matches where your Collector runs.

Move the token file to the path used in the receiver config:

sudo mkdir -p /etc/otelcol-contrib/secrets
sudo mv planetscale_token /etc/otelcol-contrib/secrets/planetscale_token
sudo chmod 600 /etc/otelcol-contrib/secrets/planetscale_token

Add this receiver to /etc/otelcol-contrib/config.yaml:

config.yaml

receivers:
  prometheus/planetscale:
    config:
      scrape_configs:
        - job_name: planetscale
          scrape_interval: 30s
          http_sd_configs:
            - url: https://api.planetscale.com/v1/organizations/<your-org>/metrics
              authorization:
                type: token
                credentials_file: /etc/otelcol-contrib/secrets/planetscale_token
              refresh_interval: 10m

Replace <your-org> with your PlanetScale organization slug.

Add prometheus/planetscale to the metrics pipeline receiver list. Keep your existing processors and exporters:

config.yaml

service:
  pipelines:
    metrics:
      receivers:
        - otlp
        - hostmetrics
        - prometheus/planetscale
      processors: [batch]
      exporters: [otlphttp]

Your existing receiver, processor, and exporter names may differ. Add prometheus/planetscale to the pipeline that sends metrics to SigNoz.

If your Collector service runs as a non-root user, give that user read access to /etc/otelcol-contrib/secrets/planetscale_token.

Check the config, then restart the Collector:

sudo /usr/bin/otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml
sudo systemctl restart otelcol-contrib

Tail the logs and check for scrape or export errors:

sudo journalctl -u otelcol-contrib -f

Add this receiver to the Collector config file you mount into the container, such as config.yaml in the same directory as your Docker Compose file or docker run command:

config.yaml

receivers:
  prometheus/planetscale:
    config:
      scrape_configs:
        - job_name: planetscale
          scrape_interval: 30s
          http_sd_configs:
            - url: https://api.planetscale.com/v1/organizations/<your-org>/metrics
              authorization:
                type: token
                credentials_file: /etc/otelcol-contrib/secrets/planetscale_token
              refresh_interval: 10m

Replace <your-org> with your PlanetScale organization slug.

Add prometheus/planetscale to the metrics pipeline receiver list. Keep your existing processors and exporters:

config.yaml

service:
  pipelines:
    metrics:
      receivers:
        - otlp
        - hostmetrics
        - prometheus/planetscale
      processors: [batch]
      exporters: [otlphttp]

Mount the token file at the credentials_file path used in the receiver config.

For Docker Compose, add this volume to the Collector service:

docker-compose.yaml

services:
  signoz-collection-agent:
    volumes:
      - ./planetscale_token:/etc/otelcol-contrib/secrets/planetscale_token:ro

Restart the Collector:

docker compose up -d
docker logs -f signoz-collection-agent

For docker run, add this mount to your existing Collector command, then rerun the container:

-v "$(pwd)/planetscale_token":/etc/otelcol-contrib/secrets/planetscale_token:ro

Create a Kubernetes Secret from the token file:

kubectl create secret generic planetscale-token \
  --from-file=planetscale_token=./planetscale_token \
  -n signoz

Add the receiver and secret mount to otelDeployment in your override-values.yaml for the SigNoz K8s Infra chart. The deployment collector runs one scraper for the cluster and avoids duplicate PlanetScale scrapes on multi-node clusters.

override-values.yaml

otelDeployment:
  config:
    receivers:
      prometheus/planetscale:
        config:
          scrape_configs:
            - job_name: planetscale
              scrape_interval: 30s
              http_sd_configs:
                - url: https://api.planetscale.com/v1/organizations/<your-org>/metrics
                  authorization:
                    type: token
                    credentials_file: /etc/otelcol-contrib/secrets/planetscale_token
                  refresh_interval: 10m
  extraVolumes:
    - name: planetscale-token
      secret:
        secretName: planetscale-token
  extraVolumeMounts:
    - name: planetscale-token
      mountPath: /etc/otelcol-contrib/secrets/planetscale_token
      subPath: planetscale_token
      readOnly: true

In the same values file, add prometheus/planetscale to otelDeployment.config.service.pipelines.metrics.receivers. Keep the receivers, processors, and exporters that your chart values use.
Deploy the chart update:

helm upgrade --install <release-name> signoz/k8s-infra \
  -n signoz \
  -f override-values.yaml

Check the Collector logs:

kubectl get pods -n signoz
kubectl logs -n signoz <collector-pod-name> -f

To learn more about PlanetScale setup, see the PlanetScale Vitess Prometheus guide and the PlanetScale Postgres Prometheus guide.

Validate

Open Metrics Explorer in SigNoz and search for planetscale_.

Metrics appear after the first successful scrape. New branches can take up to 10 minutes to appear because the service discovery refresh interval is 10m.

*PlanetScale metrics in SigNoz Metrics Explorer*

Vitess branches emit planetscale_vtgate_*, planetscale_vttablet_*, planetscale_mysql_*, and planetscale_pods_* metrics. Postgres branches emit planetscale_postgres_*, planetscale_pgbouncer_*, planetscale_pods_*, and planetscale_volume_* metrics.

For complete metric lists, see the PlanetScale Vitess metrics reference and the PlanetScale Postgres metrics reference.

Troubleshooting

No `planetscale_` metrics in SigNoz

Check the Collector logs for scrape errors:

sudo journalctl -u otelcol-contrib -f

For Docker, use docker logs -f signoz-collection-agent. For Kubernetes, use the Collector pod logs in the signoz namespace.

If the logs show discovery or authentication errors:

Confirm the token file contains <token-id>:<token> with no spaces.
Confirm the service token has read_metrics_endpoints organization access.
Confirm <your-org> matches the PlanetScale organization slug.
Confirm the Collector can reach https://api.planetscale.com.

You can test PlanetScale discovery from a shell that has the token file:

curl -sS \
  -H "Authorization: token $(cat planetscale_token)" \
  "https://api.planetscale.com/v1/organizations/<your-org>/metrics"

A successful response returns Prometheus scrape targets as JSON. An empty response points to a wrong organization slug, a token without permission, or an organization with no eligible branches.

Authentication errors (401 or 403)

Regenerate the service token if you did not save the token value during creation. PlanetScale does not show the token value again.

Then update the planetscale_token file, remount or recopy it for your environment, and restart the Collector.

Branches not appearing in SigNoz

PlanetScale service discovery refreshes every 10 minutes in the config above. Wait one full refresh cycle after creating a branch, or restart the Collector to force a fresh discovery request.

Some metric groups are missing

Check the database type first. Vitess metrics and Postgres metrics use different prefixes.

Next Steps

Import the prebuilt PlanetScale PostgreSQL and PlanetScale Vitess (MySQL) dashboards.
Use the query builder to start building dashboards with your PlanetScale metrics.
Read how to Set up Alerts in SigNoz.

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.

Send PlanetScale Metrics to SigNoz with OpenTelemetry

Overview

Prerequisites

Steps

Step 1: Create a PlanetScale service token

Step 2: Configure your deployment

Validate

Troubleshooting

No `planetscale_` metrics in SigNoz

Authentication errors (401 or 403)

Branches not appearing in SigNoz

Some metric groups are missing

Next Steps

Get Help

Was this page helpful?

Is this page helpful?

Send PlanetScale Metrics to SigNoz with OpenTelemetry

Overview

Prerequisites

Steps

Step 1: Create a PlanetScale service token

Step 2: Configure your deployment

Validate

Troubleshooting

No planetscale_ metrics in SigNoz

Authentication errors (401 or 403)

Branches not appearing in SigNoz

Some metric groups are missing

Next Steps

Get Help

Was this page helpful?

Is this page helpful?

No `planetscale_` metrics in SigNoz