Version 2026.05 has been released
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Onboard your first PostgreSQL cluster

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:

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:

Verify it is loaded:

3

Install the optional extensions

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


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.

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


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:

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

Reload the configuration:


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.

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:

  3. Register it through the Agent CLI:

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

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.

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:


Where to go next

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

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.

Last updated