Prometheus metrics for PlanetScale Postgres

Overview

See our Prometheus integration documentation for how to set Prometheus up to automatically discover and scrape metrics for your database branches. If you’re using Datadog, see our Datadog tutorial for how to setup your Datadog agent to scrape metrics for your branch.

Metrics

PlanetScale Postgres emits the following metrics to be scraped.

Database Metrics

Name & Description	Type	Tags
planetscale_postgres_connection_state The count and state of Postgres connections	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_connection_state, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wal_archiver_succeeded_count The count of successfully archived WALs	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wal_archiver_failed_count The count of unsuccessfully archived WALs	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wal_archiver_last_age_succeeded The age of the last successfully archived WAL	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wal_archiver_lag_bytes WAL bytes written but not yet archived (current LSN minus last archived LSN)	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wal_size_bytes The cumulative disk size of WALs waiting to be archived	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_settings_max_connections The current value of the max_connections setting	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_settings_max_wal_size_bytes The current value of the max_wal_size_bytes setting	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_settings_max_slot_wal_keep_size_bytes The current value of the max_slot_wal_keep_size setting (-1 means unlimited)	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_replication_slot_max_wal_retained_bytes The largest amount of WAL retained behind any logical replication slot on the primary; grows toward max_slot_wal_keep_size as a slot’s consumer falls behind	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_replication_slot_min_safe_wal_size_bytes The smallest remaining headroom before a logical replication slot risks invalidation; absent when max_slot_wal_keep_size is unlimited	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_replication_slots_lost The number of logical replication slots on the primary that have been invalidated (lost) and must be resynced	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_replica_lag_seconds Replica lag in fine-grained seconds from Postgres	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_locks Count of current lock modes	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_lock_mode, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_wait_events Count of active Postgres backends on the primary by wait event. An active backend with no wait event is running on CPU and is reported with wait event and wait event type CPU. Primary only; replicas emit no series	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_wait_event_type, planetscale_wait_event, planetscale_role, planetscale_cell, planetscale_component
planetscale_postgres_database_xact_commit_total Total committed transactions on Postgres databases	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_database_name, planetscale_role, planetscale_cell, planetscale_component
planetscale_backup_restore_active Determines if a backup restore is active, tagged with the current phase (1 = active)	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_phase, planetscale_component
planetscale_backup_fetch_percent Percentage progress of a backup fetch operation (0-100)	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_component

Edge Metrics

Name & Description	Type	Tags
planetscale_edge_postgres_active_connections The number of active Postgres and PgBouncer connections to the branch	Gauge	cluster, planetscale_database_branch_id, planetscale_port, planetscale_region
planetscale_edge_postgres_connection_drops_total The total number of Postgres and PgBouncer connections that have been dropped	Counter	cluster, planetscale_database_branch_id, planetscale_port, planetscale_region
planetscale_edge_postgres_connection_errors_total The total number of Postgres and PgBouncer connections that have resulted in an error	Counter	cluster, planetscale_database_branch_id, planetscale_port, planetscale_region
planetscale_edge_postgres_bytes_sent_total The total number of Postgres and PgBouncer bytes sent	Counter	cluster, planetscale_database_branch_id, planetscale_port, planetscale_connector_id, planetscale_region
planetscale_edge_postgres_bytes_received_total The total number of Postgres and PgBouncer bytes received	Counter	cluster, planetscale_database_branch_id, planetscale_port, planetscale_connector_id, planetscale_region

PgBouncer Metrics

Name & Description	Type	Tags
planetscale_pgbouncer_total_peers The total count of peered processes PgBouncer is running	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_cpu_util_per_peer_percentages CPU utilization percentage of PgBouncer peered processes	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_current_connections The current count PgBouncer connections to Postgres	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_current_client_connections The current count client connections to PgBouncer	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_pools_client The count and state of PgBouncer client connections	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_pgbouncer_pool, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_pools_client_maxwait_seconds How long the first client connection has waited to connect to PgBouncer	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pgbouncer_pools_server The count and state of PgBouncer server connections	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_pgbouncer_pool, planetscale_role, planetscale_cell, planetscale_component

Infrastructure Metrics

Name & Description	Type	Tags
planetscale_pods_cpu_util_percentages CPU utilization percentage of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_mem_util_percentages Memory utilization percentage of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_iops_total Total IOPS (Input/Output Operations Per Second) of database pods	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_volume_available_bytes Available storage space in bytes on Postgres volumes	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_volume_capacity_bytes Total storage capacity in bytes on Postgres volumes	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_mem_rss_bytes RSS memory usage in bytes of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_mem_mmap_bytes Memory-mapped file usage in bytes of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_mem_active_cache_bytes Active cache memory in bytes of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_mem_inactive_cache_bytes Inactive cache memory in bytes of database pods	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component
planetscale_pods_container_status_restarts_total Total container restarts, across all restart reasons. Join planetscale_pods_container_last_terminated_reason to attribute them	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_cell, planetscale_component
planetscale_pods_container_last_terminated_reason Reason a container was last terminated (1 = the current reason). Join against planetscale_pods_container_status_restarts_total to attribute restarts to a reason	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_cell, planetscale_component, planetscale_restart_reason
planetscale_pods_status_phase Pod status phase (Running, Pending, Failed, Succeeded, Unknown). Carries the pod’s role, so join it to break container restarts down by role	Gauge	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_phase, planetscale_role, planetscale_cell, planetscale_component

Deprecated Metrics

These metrics are deprecated and will be removed eventually.

Name & Description	Type	Tags
planetscale_pods_container_restarts_total Total container restart events detected. The reason label is attached to an all-reasons total and the counter cannot be observed at zero, so rates and increases over it are wrong in both directions. Replaced by planetscale_pods_container_status_restarts_total.	Counter	cluster, planetscale_database_branch_id, planetscale_pod, planetscale_container, planetscale_role, planetscale_cell, planetscale_component, planetscale_restart_reason

Attributing Container Restarts

planetscale_pods_container_status_restarts_total counts every restart and carries no role or reason label. Join the metric that carries the one you want. To break restarts down by role, join planetscale_pods_status_phase:

sum by (planetscale_role) (
  increase(planetscale_pods_container_status_restarts_total[1h])
  * on (planetscale_pod) group_left(planetscale_role)
  group by (planetscale_pod, planetscale_role) (planetscale_pods_status_phase)
)

To break restarts down by reason as well, filter against planetscale_pods_container_last_terminated_reason one minute at a time and join the role onto the result:

sum by (planetscale_role) (
  sum_over_time((
    increase(planetscale_pods_container_status_restarts_total[1m])
    and on (planetscale_pod, planetscale_container)
    planetscale_pods_container_last_terminated_reason{planetscale_restart_reason="OOMKilled"}
  )[1h:1m])
  * on (planetscale_pod) group_left(planetscale_role)
  group by (planetscale_pod, planetscale_role) (planetscale_pods_status_phase)
)

The gauge only reports a container’s latest termination reason, so the query attributes each minute’s restarts to the reason current in that minute, then sums over the hour. Change 1h to your own window and leave the 1m alone. A container that restarts twice inside one minute under two different reasons has both restarts attributed to the later one.

Tag Glossary

cluster: The PlanetScale cluster identifier
planetscale_access: The access path on bytes sent/received metrics (public for traffic over the public internet, or private for traffic over AWS PrivateLink or GCP Private Service Connect)
planetscale_database_branch_id: The unique identifier for the database branch
planetscale_pod: The Kubernetes pod name
planetscale_container: The container name (postgres, pgbouncer, walg-daemon)
planetscale_role: The database role (primary, replica). Absent on pods that have no role, such as pgbouncer
planetscale_cell: The PlanetScale cell identifier
planetscale_phase: The pod’s status phase (Running, Pending, Failed, Succeeded, Unknown)
planetscale_component: The PlanetScale component identifier
planetscale_connection_state: The state of database connections
planetscale_lock_mode: The PostgreSQL lock mode
planetscale_wait_event_type: The PostgreSQL wait event type of an active backend (for example Lock, LWLock, IO, Client), or CPU when the backend is not waiting
planetscale_wait_event: The PostgreSQL wait event of an active backend (for example transactionid, DataFileRead, ClientRead), or CPU when the backend is not waiting
planetscale_database_name: The PostgreSQL database name
planetscale_port: The connection port number
planetscale_region: The geographic region
planetscale_pgbouncer_pool: The PgBouncer connection pool identifier
planetscale_connector_id: The edge connector identifier
planetscale_restart_reason: Reason for a container’s most recent termination (OOMKilled, Error, Completed). Carried by planetscale_pods_container_last_terminated_reason

Need help?

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

Onboarding

Platform

Guides

Prometheus metrics for PlanetScale Postgres

Overview

Metrics

Database Metrics

Edge Metrics

PgBouncer Metrics

Infrastructure Metrics

Deprecated Metrics

Attributing Container Restarts

Tag Glossary

Need help?

​Overview

​Metrics

​Database Metrics

​Edge Metrics

​PgBouncer Metrics

​Infrastructure Metrics

​Deprecated Metrics

​Attributing Container Restarts

​Tag Glossary

​Need help?

Overview

Metrics

Database Metrics

Edge Metrics

PgBouncer Metrics

Infrastructure Metrics

Deprecated Metrics

Attributing Container Restarts

Tag Glossary

Need help?