PlanetScale CLI commands: metrics

Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

The metrics command

Query historical and current branch metrics from PlanetScale’s metrics service. Human output summarizes time series with latest, min, average, max, and a sparkline trend. JSON preserves the API response for automation. CSV emits one row per sample or current value for scripts and analysis tools.

For server-side query analysis (slow queries, anomalies, schema recommendations), use pscale insights. For live connection-level diagnostics, use pscale inspect. To ask an AI assistant for the same metrics, use planetscale_get_branch_metrics.

Requires pscale 0.321.0 or later.

Usage:

pscale metrics <sub-command> <database> <branch> --org <org> <FLAG>

Place positional arguments first, then flags. --org is required.

Available sub-commands

Sub-command	Product	Description
show	Vitess, Postgres	Historical metric time series over a named period or custom range
instant	Vitess, Postgres	Current metric values
report	Vitess, Postgres	Engine-aware grouped performance report (MySQL and PostgreSQL use different sections)
queries	Vitess, Postgres	Historical metrics for selected SQL query patterns
tables	Vitess, Postgres	Table storage metrics
keyspace-tables	Vitess	Table storage metrics grouped by keyspace
tablets	Vitess	Historical tablet metric series
tablets instant	Vitess	Current tablet metric values
tags	Vitess, Postgres	Historical metrics grouped by query tag sets

Available flags

Flag	Description
--org <org>	Organization name (required)
-f, --format <FORMAT>	Show output in a specific format. Possible values: human (default), json, csv.
-h, --help	Help for metrics

Examples

The show sub-command

Query historical metric series for a branch. --metric is required and may be repeated or comma-separated.

Usage:

pscale metrics show <database> <branch> --org <org> --metric <metric> <FLAG>

Available flags:

Flag	Description
--metric <name>	Metric to query (repeat or comma-separate) (required)
--period <duration>	Named time period (for example 1h, 12h, or 1d; defaults to 12h)
--from <timestamp>	Start of a custom time range as an ISO 8601 timestamp (use with --to)
--to <timestamp>	End of a custom time range as an ISO 8601 timestamp (use with --from)
--steps <n>	Requested number of data points
--tablet-type <type>	Filter by tablet type (Vitess)
--keyspace <name>	Filter by keyspace (Vitess)
--shard <shard>	Filter by shard
--role <role>	Filter by Postgres role
--container <name>	Filter by container
--pod <name>	Filter by one pod
--pods <name>	Filter by pods (repeat or comma-separate)
--query-id <id>	Filter by query pattern ID (repeat or comma-separate)
--fingerprint <hash>	Filter by query fingerprint
--budget-id <id>	Filter by traffic budget ID
--rule-id <id>	Filter by traffic rule ID
-q, --search <terms>	Filter by search terms

--period cannot be combined with --from and --to. Both range flags must be set together.

Examples:

pscale metrics show <database> <branch> --org <org> --metric queries --metric latency_p99 --period 1h
pscale metrics show <database> <branch> --org <org> --metric queries --period 1h --format csv
pscale metrics show <database> <branch> --org <org> --metric queries --period 1h --format json

The instant sub-command

Show current metric values. --metric is required and may be repeated or comma-separated.

Usage:

pscale metrics instant <database> <branch> --org <org> --metric <metric> <FLAG>

Available flags:

Flag	Description
--metric <name>	Metric to query (repeat or comma-separate) (required)
--role <role>	Filter by Postgres role
--shard <shard>	Filter by shard
--container <name>	Filter by container
--pod <name>	Filter by pod

Examples:

pscale metrics instant <database> <branch> --org <org> --metric planetscale_volume_usage_percentage
pscale metrics instant <database> <branch> --org <org> --metric planetscale_volume_usage_percentage --format json

The report sub-command

Produce a curated performance report for a branch. The database engine is detected automatically. MySQL (Vitess) and PostgreSQL reports include different metric sections, including current-value sections where applicable. Section headings are bold in human output and plain text with --no-color.

Usage:

pscale metrics report <database> <branch> --org <org> <FLAG>

Available flags:

Flag	Description
--period <duration>	Named report period: 15m, 1h, 3h, 6h, 12h, 1d, 2d, 7d, or 8d (default 1d)
--from <timestamp>	Start of a custom time range as an ISO 8601 timestamp (use with --to)
--to <timestamp>	End of a custom time range as an ISO 8601 timestamp (use with --from)
--steps <n>	Requested number of historical data points

Examples:

pscale metrics report <database> <branch> --org <org> --period 1d
pscale metrics report <database> <branch> --org <org> --period 7d --no-color
pscale metrics report <database> <branch> --org <org> --period 1d --format json

Report sections

Vitess (MySQL) reports include:

• Workload, errors, and traffic control
• Latency and execution time
• Query efficiency and fan-out
• Buffer and block activity
• Network traffic
• VTGate utilization by availability zone
• Storage by table

PostgreSQL reports include the sections above (with Postgres-specific network and connection metrics) plus:

• Edge network traffic
• Connections and connection pooling
• CPU, memory utilization, and IOPS
• PostgreSQL memory composition
• Storage utilization
• Transactions, replication, and WAL
• Pod health
• Current connection capacity (instant values)
• Current storage capacity (instant values)
• Backup activity (instant values)

The queries sub-command

Show metrics for selected SQL query patterns. --metric is required. Select queries with --fingerprint and --keyspace together, or with --query-id as <fingerprint>-<keyspace>. The short id from insights queries is not a query pattern ID. --query-id cannot be combined with --fingerprint or --keyspace.

Filters that match nothing return zero-filled series rather than an empty response, so check the point values, not the series count.

pscale metrics queries <database> <branch> --org <org> --metric latency_p99 --fingerprint <fingerprint> --keyspace <keyspace> --period 1h

The tables and keyspace-tables sub-commands

Show storage metrics for tables. JSON preserves the untyped storage-metrics API response.

pscale metrics tables <database> <branch> --org <org>
pscale metrics keyspace-tables <database> <branch> --org <org>

The tablets sub-command

Show tablet metric series. --metric is required. --workflow applies only to --metric vreplication_lag. The CLI does not check that the workflow exists locally.

pscale metrics tablets <database> <branch> --org <org> --metric replication_lag --period 1h
pscale metrics tablets instant <database> <branch> --org <org> --metric replication_lag

The tags sub-command

Show metrics grouped by query tags. --metric is required, and at least one --tag-set is required. Repeat --tag-set for independent series; comma-separate keys inside one set (Busername=alice,Senv=production). Tag keys need the Insights type prefix from insights tags. --budget-id and --rule-id apply only to the traffic_control_warnings and traffic_control_throttled metrics.

pscale metrics tags <database> <branch> --org <org> --metric queries --tag-set Busername=alice --tag-set Busername=bob --period 1h

JSON and CSV output

Use --format json for automation.

Historical (show): start_date, end_date, interval, and series. Each series contains metric, label, labels, and [Unix timestamp, value] points.

Instant (instant): current values grouped by metric and dimensions.

Report (report): composite JSON with engine, period (or from/to), and sections containing the underlying series or instant results. CSV includes a section column on each row.

Metric names

Pass metric identifiers to --metric. Common examples include queries, latency_p99, connections, and planetscale_volume_usage_percentage. For the full list accepted by the API, see Get time-series metrics and Get instant branch metrics.

Prometheus metric names for scraping are documented separately in the Vitess Prometheus metrics reference and Postgres Prometheus metrics.

Related documentation

pscale insights

pscale inspect

Cluster metrics (Postgres)

Metrics API reference

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.