If you’re looking for more metrics than PlanetScale’s native Datadog integration provides, this tutorial will show how to configure your Datadog agent to scrape PlanetScale’s Prometheus infrastructure automatically, allowing you to collect detailed metrics for all of your PlanetScale branches.
In this tutorial, we’ll assume that you have a Datadog Agent Version 7 running. For more information on what the Datadog Agent is and how to install it, start with the Datadog Agent documentation.For the purposes of this guide, we’ll be using a Datadog agent running with the recommended installation steps on a Linux system.
You’ll need a working Datadog agent and access to add a Custom Agent Check to that instance. This may require root or sudo access on the machine running the Datadog agent.You’ll also need a Service token in your Organization, with the read_metrics_endpoints permission granted.
Go to https://github.com/planetscale/planetscale-datadog, which is the repository that has our custom OpenMetrics Check.Place the unedited planetscale.py in the checks.d directory of your Datadog Agent.
On Linux, that is /etc/datadog-agent/checks.d/
On macOS, that is /opt/datadog-agent/etc/checks.d/
Make sure that it belongs to the appropriate user. If you’re using the recommended Linux installation steps, it will have created a dd-agent user:
This file is owned by the dd-agent user and group in the /etc/datadog-agent/checks.d directory.If you’re on macOS, it will depend on whether you installed the agent as a ‘Single User Agent’ or a ‘Systemwide Agent’. If you picked Single User, there should be no additional permission changes needed. If you installed it as a Systemwide agent, make sure the user and group you installed the agent with as ownership of the file.
Now that we have the plugin installed, we need to configure it. In the conf.d directory of the Datadog agent take the conf.d/planetscale.yaml.example file and edit it with your organization name and Service Token information. It should look like this:
instances: - planetscale_organization: 'nick' # Required: Your PlanetScale organization ID ps_service_token_id: '${TOKEN_ID}' # Required: Your PlanetScale Service Token ID ps_service_token_secret: '${TOKEN}' # Required: Your PlanetScale Service Token Secret. Consider using Datadog secrets management: https://docs.datadoghq.com/agent/guide/secrets-management/ namespace: 'planetscale' # Required: Namespace for the metrics metrics: # Required: List of metrics to collect. Use mapping for renaming/type overrides. - planetscale_vtgate_queries_duration: vtgate_query_duration min_collection_interval: 60 send_distribution_buckets: true collect_counters_with_distributions: true
This configures the integration to look for all of the branches in the "nick" PlanetScale organization, only collect the planetscale_vtgate_queries_duration metric, which it will rename vtgate_query_duration and put it inside of the planetscale namespace.
Using '.*' in the metrics list tells the Datadog agent to scrape all metrics exposed by PlanetScale. This is useful when you want comprehensive monitoring without manually maintaining a list of specific metrics.Save the file at planetscale.yaml, making sure to double check permissions:
Now that the Datadog Agent is running the PlanetScale plugin, metrics should start flowing into Datadog within a couple of minutes. To validate, we can ask the Datadog Agent:
If the plugin is installed successfuly, this should output the scrape targets for your branches, as well as metadata about when it was last run and how many metrics were emitted:
$ sudo -u dd-agent -- datadog-agent check planetscale=== Service Checks ===[ { "check": "planetscale.api.can_connect", "host_name": "ubuntu", "timestamp": 1743638192, "status": 0, "message": "", "tags": [ "planetscale_org:nick" ] }, { "check": "planetscale.prometheus.health", "host_name": "ubuntu", "timestamp": 1743638192, "status": 0, "message": "", "tags": [ "endpoint:https://metrics.psdb.cloud/metrics/branch/7wxuxewx4l0p?..." ] }, { "check": "planetscale.prometheus.health", "host_name": "ubuntu", "timestamp": 1743638192, "status": 0, "message": "", "tags": [ "endpoint:https://metrics.psdb.cloud/metrics/branch/6o0rr27785fl?..." ] }] Running Checks ============== planetscale (unversioned) ------------------------- Instance ID: planetscale:planetscale:8d4d64f696d967be [OK] Configuration Source: file:/etc/datadog-agent/conf.d/planetscale.yaml Total Runs: 1 Metric Samples: Last Run: 0, Total: 0 Events: Last Run: 0, Total: 0 Service Checks: Last Run: 3, Total: 3 Histogram Buckets: Last Run: 77, Total: 77 Average Execution Time : 809ms Last Execution Date : 2025-04-02 23:56:32 UTC (1743638192000) Last Successful Execution Date : 2025-04-02 23:56:32 UTC (1743638192000) Metadata ======== config.hash: planetscale:planetscale:8d4d64f696d967be config.provider: file
The Service Checks show that it has successfully connected to the PlanetScale API to request information about how to scrape for the branches in my organization, and it has successfully scraped both of what it discovered.We can also see that it successfully executed at 2025-04-02 23:56:32 UTC and produced 77 Histogram Buckets.
Starting in Datadog Agent v7.32.0, in adherence to the OpenMetrics specification standard, counter names ending in _total must be specified without the _total suffix. For example, to collect promhttp_metric_handler_requests_total, specify the metric name promhttp_metric_handler_requests. This submits to Datadog the metric name appended with .count, promhttp_metric_handler_requests.count.
This means that to scrape a metric such as planetscale_mysql_bytes_received_total, you would configure the Datadog agent for planetscale_mysql_bytes_received.If I want to collect additional metrics, I can add them to the list:
metrics: # Required: List of metrics to collect. Use mapping for renaming/type overrides. - planetscale_vtgate_queries_duration: vtgate_query_duration - planetscale_edge_active_connections: active_connections
Then, restart the Datadog Agent:
$ sudo systemctl restart datadog-agent
If I check the status of the PlanetScale Plugin, I can see our last run added a Metric Sample:
Running Checks ============== planetscale (unversioned) ------------------------- Instance ID: planetscale:planetscale:fde586b60a54a38f [OK] Configuration Source: file:/etc/datadog-agent/conf.d/planetscale.yaml Total Runs: 1 Metric Samples: Last Run: 1, Total: 1 Events: Last Run: 0, Total: 0 Service Checks: Last Run: 3, Total: 3 Histogram Buckets: Last Run: 77, Total: 77 Average Execution Time : 826ms Last Execution Date : 2025-04-03 00:01:45 UTC (1743638505000) Last Successful Execution Date : 2025-04-03 00:01:45 UTC (1743638505000)
In the Datadog UI, I can see data for the planetscale.active_connections metric:
