Onboard Your First PostgreSQL Cluster

The golden path from a brand-new PostgreSQL instance to a fully monitored cluster: extensions, monitoring user, network access, connection, and tags.

This guide walks you from a freshly installed Datasentinel platform to your first monitored PostgreSQL cluster, end to end. By the end you will have:

1. The required PostgreSQL extension installed (and the optional ones you want).

2. A dedicated read-only monitoring user.

3. Network access opened from Datasentinel to your instance.

4. The instance registered in Datasentinel, either through a local agent or agentlessly.

5. A clean tagging scheme that will scale to dozens of clusters.

You only need to do this once per cluster. Tagging it well from day one pays off later for filtering dashboards, consolidating workloads, and scoping role-based access.

Prerequisites

Before you begin, make sure you have:

Requirement	Detail
PostgreSQL version	10 or later (older versions require a superuser monitoring account).
Superuser access	Needed only for the one-time setup (install extension, create user, edit postgresql.conf / pg_hba.conf).
Network path	The Datasentinel platform (agentless) or a local Datasentinel agent must reach the PostgreSQL port.
Datasentinel platform	Installed and reachable. See Installation › Platform.

---

Step 1: Install the required extension

Datasentinel depends on pg_stat_statements to collect per-query execution statistics. This is the only mandatory extension. Three more are optional and unlock additional features.

1

Preload the extension

Edit postgresql.conf and add pg_stat_statements to shared_preload_libraries, plus the recommended settings:

shared_preload_libraries = 'pg_stat_statements'

# Track all statements
pg_stat_statements.track = all

# Optional, not necessary for Datasentinel to save pg_stat_statements
pg_stat_statements.save = false

# Reduce the default 5000 to e.g. 2000. Datasentinel collects metrics at regular intervals
pg_stat_statements.max = 2000

# Since PostgreSQL 14
compute_query_id = on

# Log I/O timing
track_io_timing = on

A PostgreSQL restart is required for shared_preload_libraries to take effect.

2

Create the extension

Connect to the internal postgres database as superuser and run:

CREATE EXTENSION pg_stat_statements;

Verify it is loaded:

SELECT current_database(), extname
FROM pg_extension
WHERE extname = 'pg_stat_statements';

3

Install the optional extensions

These add capabilities that you will likely want later. Install them now to avoid a second maintenance window.

pg_store_plans

Captures and exposes execution plans for every tracked query.

system_stats

Reports CPU, memory and disk metrics from the database host (useful when the agentless model can't reach the OS).

pg_buffercache

Required by Live360 to surface the Disk & Cache Usage view.

---

Step 2: Create the monitoring user

Datasentinel uses a dedicated, read-only PostgreSQL user. It never writes data. Access is restricted to the system catalogs needed to retrieve metrics.

PostgreSQL >= 10

CREATE USER datasentinel PASSWORD 'myPassword';
GRANT pg_monitor, pg_read_all_settings, pg_read_all_stats TO datasentinel;

If you want to terminate sessions from the Datasentinel UI (Live360), also grant:

GRANT pg_signal_backend TO datasentinel;

PostgreSQL < 10

The default PostgreSQL search_path is "$user", public. If you have changed it at the instance level, make sure the datasentinel user can still see the public schema:

ALTER USER datasentinel SET search_path TO "$user", public;

---

Step 3: Open the network path

Edit pg_hba.conf so the monitoring user can authenticate from the Datasentinel platform (agentless) or the host running the local agent:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             datasentinel    <datasentinel_ip>/32    md5

The user must be able to connect to all databases on the instance. That is how Datasentinel discovers per-database activity.

Reload the configuration:

SELECT pg_reload_conf();

---

Step 4: Register the instance

You have two ways to connect Datasentinel to your cluster. They are functionally equivalent: pick the one that fits your environment. Unsure? See the Architecture comparison.

Agent-based

Install a local Datasentinel agent on (or near) the PostgreSQL host. The agent connects to the database, collects metrics, and pushes them to the platform.

1. Install the agent. See Installation › Agent.

2. Describe the connection in a JSON file:

   cat > myInstance.json <<EOF
   {
     "host": "host_name",
     "port": 5432,
     "user": "datasentinel",
     "password": "myPassword",
     "tags": "application=sales,environment=production,datacenter=eu-west"
   }
   EOF

3. Register it through the Agent CLI:

   datasentinel add connection sales-prod -f myInstance.json

An example script connection_example.sh is shipped in the datasentinel subdirectory.

Agentless

Within a minute of registration, the instance shows up on the Datasentinel Home dashboard and the first metrics begin to flow.

---

Step 5: Tag for the long run

The tags field you set in Step 4 is more than a label: it is the single source of truth for filtering dashboards, consolidating workloads across primaries and replicas, and scoping role-based access. Pick a strategy on day one and apply it consistently.

A pragmatic baseline that scales:

Tag key	Example values	Why
application	sales, inventory, billing	Group instances by the product or service they serve. Drives most dashboards and RBAC.
environment	production, staging, development	Separate critical workloads, restrict developer access to non-prod, drive alert severity.
cluster	orders, analytics	Required to consolidate the workload across HA primaries and replicas.
datacenter	eu-west, us-east, on-prem-fr	Geo or provider context for incident triage.
owner	team-payments	So the responsible team is one click away from any dashboard.

Datasentinel adds a set of automatic tags (server, PostgreSQL version, database, wait events…). Your custom tags complement them. Keep keys short, lowercase and consistent.

---

Step 6: Verify and explore

Open Datasentinel and confirm the new instance is collecting data:

Home

Your cluster should appear in the global list with its tags applied as filters.

Session History

Within a minute, the Active Session History chart starts populating: confirmation that the agent or platform is sampling.

Top Queries

After a few minutes of activity, per-query stats from pg_stat_statements appear here.

Live360

Open it to confirm your monitoring user has the right grants (Disk & Cache requires pg_buffercache).

---

Where to go next

Now that your first cluster is monitored, build on it:

Manage Users and Role-Based Access: give the right people access to the right instances, based on the tags you just set.

Monitor High-Availability Clusters: add the primary and its replicas, then consolidate the workload at the cluster level.

Monitor Cloud-Managed Instances: onboard RDS, Azure, Cloud SQL and other managed services agentlessly.

Automate with the API: register the next clusters, users and roles from a script instead of the UI.

Conclusion

In six short steps you have moved a PostgreSQL instance from invisible to fully observable: the right extension is loaded, a read-only monitoring user is in place, the network path is open, the connection is registered, and your tagging scheme is ready to carry the rest of your fleet. The same recipe (extensions, user, network, register, tag, verify) applies to every cluster you add next.