Databases & overview

Databases list

Databases lists every registered database, grouped by environment and showing its status. Search matches name, host or database name, and you can filter by status, environment and tags. Each filter chip shows how many databases match, counted under the other filters in effect.

Status	Meaning
REGISTERED	Saved, not connected yet.
CONNECTING	A connection is being established.
CONNECTED	The last connection test succeeded.
COLLECTING	Telemetry is arriving.
DEGRADED	Reachable, with capabilities missing.
OFFLINE	The last connection attempt failed.

Adding a database

Databases → Add database asks for:

Field	Notes
Name	Display name, e.g. orders-primary.
Host, port	As reachable from the API.
Database name	The database to observe.
Username, password	The least-privilege monitoring role. The password is encrypted at rest.
SSL mode	disable, prefer (default), require, verify-ca, verify-full.
Environment	Optional: production, staging, development, testing or other.
Tags	Optional labels such as checkout or eu-west.

Environments and tags

Once you watch more than a handful of databases, “which of these is production?” matters more than any single metric.

• Environment is one value per database, from a fixed list: production, staging, development, testing or other. Databases without one are grouped as unassigned. Production sorts first everywhere.
• Tags are free-form labels, up to 20 per database, for anything else: a service (checkout), a region (eu-west), a tier (tier-1). A tag is lowercase and may contain letters, digits and . _ : -, up to 32 characters. Typing a tag that already exists elsewhere suggests it, so labels stay consistent.

Both are shown on the database header, the dashboard and the databases list, and both can be changed at any time under Settings → General on the database page. Filtering by several tags shows only databases carrying all of them; clicking a tag chip anywhere adds it to the filter.

PATCH /api/v1/databases/{id}
Content-Type: application/json

{ "environment": "production", "tags": ["checkout", "eu-west"] }

Send "environment": null to clear it. Only the fields you send are changed, and every change is recorded in the audit trail.

Test connection checks the credentials without saving them and returns the capability checklist, so a missing pg_stat_statements shows up before you commit credentials. Testing is encouraged but not required. Registering the same database twice is rejected.

Database page

Each database page is made of independent panels; if one cannot load, the others still work.

Header and capabilities

The header shows user@host:port/database, the SSL mode and when the database last connected. The Capabilities panel collapses to one line (for example “All 6 capabilities available · 12 ms”), and Details expands the checklist. Test connection re-tests the stored credentials and refreshes the stored capabilities and status. Details open automatically when a test finds something to fix.

Overview

Database-wide figures over a selectable window: the last 15 minutes, 1 hour, 6 hours, 24 hours, 7 days, or a custom from/to range (up to 7 days). The window lives in the URL, so links are shareable.

Tiles

Tile	Definition
Calls/min	Executions per minute across all queries.
Mean latency	Exact: total execution time ÷ calls.
Load	Average number of queries executing at once: total execution time ÷ wall time.
Cache hit ratio	Shared buffer hits ÷ all shared blocks touched.
Connections	Current total of max_connections, with active and idle-in-transaction counts.
Blocked sessions	Peak number of sessions waiting on a lock in the window.

Percentiles are deliberately not shown here: pooled across unrelated queries they mean nothing.

Charts: throughput, mean latency, load, connections by state (with sessions blocked on locks), cache hit ratio, and I/O (shared blocks read, temp blocks written). Hover or use the arrow keys for exact values.

Time by statement type: each type’s share of execution time, with calls, mean and the number of distinct queries.

Largest tables: size, live rows, dead-tuple ratio (highlighted from 20%) and sequential vs index scans, from the most recent table-statistics sample.

Top queries

The five queries with the most total execution time in the last hour, with calls, mean and estimated p95. Open query explorer for filtering, sorting and paging; see Top queries & explorer.

Agents and settings

See Installing the agent and Database settings.

Removing a database

The Danger zone deletes the database registration together with its agents and all telemetry collected for it. This cannot be undone. Stop the agent processes afterwards; their tokens no longer work.