;
};
## Getting Started
Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup). 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`](/docs/cli/insights). For live connection-level diagnostics, use [`pscale inspect`](/docs/cli/inspect).
**Requires `pscale` 0.321.0 or later.**
**Usage:**
```bash theme={null}
pscale metrics --org
```
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 ` | Organization name **(required)** |
| `-f`, `--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:**
```bash theme={null}
pscale metrics show --org --metric
```
**Available flags:**
| **Flag** | **Description** |
| ------------------------ | ----------------------------------------------------------------------- |
| `--metric ` | Metric to query (repeat or comma-separate) **(required)** |
| `--period ` | Named time period (for example `1h`, `12h`, or `1d`; defaults to `12h`) |
| `--from ` | Start of a custom time range as an ISO 8601 timestamp (use with `--to`) |
| `--to ` | End of a custom time range as an ISO 8601 timestamp (use with `--from`) |
| `--steps ` | Requested number of data points |
| `--tablet-type ` | Filter by tablet type (Vitess) |
| `--keyspace ` | Filter by keyspace (Vitess) |
| `--shard ` | Filter by shard |
| `--role ` | Filter by Postgres role |
| `--container ` | Filter by container |
| `--pod ` | Filter by one pod |
| `--pods ` | Filter by pods (repeat or comma-separate) |
| `--query-id ` | Filter by query pattern ID (repeat or comma-separate) |
| `--fingerprint ` | Filter by query fingerprint |
| `--budget-id ` | Filter by traffic budget ID |
| `--rule-id ` | Filter by traffic rule ID |
| `-q`, `--search ` | Filter by search terms |
`--period` cannot be combined with `--from` and `--to`. Both range flags must be set together.
**Examples:**
```bash theme={null}
pscale metrics show --org --metric queries --metric latency_p99 --period 1h
pscale metrics show --org --metric queries --period 1h --format csv
pscale metrics show --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:**
```bash theme={null}
pscale metrics instant --org --metric
```
**Available flags:**
| **Flag** | **Description** |
| -------------------- | --------------------------------------------------------- |
| `--metric ` | Metric to query (repeat or comma-separate) **(required)** |
| `--role ` | Filter by Postgres role |
| `--shard ` | Filter by shard |
| `--container ` | Filter by container |
| `--pod ` | Filter by pod |
**Examples:**
```bash theme={null}
pscale metrics instant --org --metric planetscale_volume_usage_percentage
pscale metrics instant --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:**
```bash theme={null}
pscale metrics report --org
```
**Available flags:**
| **Flag** | **Description** |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `--period ` | Named report period: `15m`, `1h`, `3h`, `6h`, `12h`, `1d`, `2d`, `7d`, or `8d` (default `1d`) |
| `--from ` | Start of a custom time range as an ISO 8601 timestamp (use with `--to`) |
| `--to ` | End of a custom time range as an ISO 8601 timestamp (use with `--from`) |
| `--steps ` | Requested number of historical data points |
**Examples:**
```bash theme={null}
pscale metrics report --org --period 1d
pscale metrics report --org --period 7d --no-color
pscale metrics report --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 `-`. 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.
```bash theme={null}
pscale metrics queries --org --metric latency_p99 --fingerprint --keyspace --period 1h
```
### The `tables` and `keyspace-tables` sub-commands
Show storage metrics for tables. JSON preserves the untyped storage-metrics API response.
```bash theme={null}
pscale metrics tables --org
pscale metrics keyspace-tables --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.
```bash theme={null}
pscale metrics tablets --org --metric replication_lag --period 1h
pscale metrics tablets instant --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.
```bash theme={null}
pscale metrics tags --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](/docs/api/reference/get_branch_metrics) and [Get instant branch metrics](/docs/api/reference/get_instant_branch_metrics).
Prometheus metric names for scraping are documented separately in the [Vitess Prometheus metrics reference](/docs/vitess/integrations/prometheus-metrics) and [Postgres Prometheus metrics](/docs/postgres/monitoring/prometheus-metrics-postgres).
## Related documentation
## Need help?
Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.