> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale CLI commands: metrics

Vitess and Postgres

## Getting Started

Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup.md). 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). To ask an AI assistant for the same metrics, use [`planetscale_get_branch_metrics`](/docs/mcp-server).

> [!NOTE]
>
> **Requires `pscale` 0.321.0 or later.**

**Usage:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](/docs/api/reference/get_branch_metrics.md) and [Get instant branch metrics](/docs/api/reference/get_instant_branch_metrics.md).

Prometheus metric names for scraping are documented separately in the [Vitess Prometheus metrics reference](/docs/vitess/integrations/prometheus-metrics.md) and [Postgres Prometheus metrics](/docs/postgres/monitoring/prometheus-metrics-postgres.md).

## Related documentation

> **[pscale insights](/docs/cli/insights.md)**

> **[pscale inspect](/docs/cli/inspect.md)**

> **[Cluster metrics (Postgres)](/docs/postgres/monitoring/metrics.md)**

> **[Metrics API reference](/docs/api/reference/get_branch_metrics.md)**

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.