Off-Host Installation

In off-host monitoring, the agent is installed on any compatible host, and connects to the monitored server over the network. Use this installation method if:

  • You are monitoring Amazon RDS or Aurora for PostgreSQL or MySQL
  • You are monitoring Google Cloud SQL (MySQL or Postgres 11+)
  • You are monitoring Azure MySQL or PostgreSQL (version 10+)
  • You otherwise do not have direct access to the server running the database
  • You use encrypted connections or connect to your database using sockets

Data is collected from MySQL’s PERFORMANCE_SCHEMA or PostgreSQL’s pg_stat_statements. See the Enabling PERFORMANCE_SCHEMA and pg_stat_statements section below to enable these.

Installing DPM

Open the installation wizard by clicking “Setup your first host” or “Add New Host.” Select “Off-Host” and then your database type.

Enter the address of the service you wish to monitor, as well as the credentials for DPM to use to connect. When monitoring an Amazon Aurora cluster, you will need to monitor each node as a separate instance, using the instance endpoints; do not use the general reader/writer endpoints.

Install Wizard

If you have not already created a user with the correct privileges for DPM to use, you should do that now. Select “Create User”.


The wizard provides the basic steps to create a MySQL user with the necessary privileges for the agent to monitor the database. For more information about these privileges and the purpose each of them serves, refer to the MySQL section in our Privileges documentation.

Install Wizard

Make sure you have PERFORMANCE_SCHEMA enabled (see instructions on how to enable it below).

Once the requirements are covered click on “Check configuration.”


For all versions of PostgreSQL query performance statistics are captured from the pg_stat_statements extension. The extension must be enabled (see instructions on how to enabled it below) and the monitoring user must have the SUPERUSER (or rds_superuser) privilege.

Install Wizard

We have created a script which will automate the process of installing PostgreSQL monitoring in an off-host configuration and we recommend you use it in this step. Please refer to the “Scripted” section in the Privileges page.

As an optional workaround, DPM supports non-SUPERUSER monitoring for PostgreSQL by defining functions for the monitoring user.

Once the requirements are covered click on “Check configuration.”

Check configuration

Run the given statement shown by the wizard against the database to be monitored as the created DPM user to check that the necessary extension (PERFORMANCE_SCHEMA or pg_stat_statements) has been enabled and is accessible:

MySQL Install Wizard

PostgreSQL Install Wizard

Once confirmed, click “Select the OS Host”.

Select the OS Host

In off-host monitoring installation scenarios, the agent monitors a service remotely, running on a different host of your choosing. Run the installation script on the host where the agent will live (not the host it will monitor), and select that host when it appears in the wizard. Note that you will NOT see the host which you are going to monitor, only the host where the agent will run.

Install Wizard

To install the agent off-host with the ability to migrate to other servers transparently, please refer to the “Moving Agents to a New Host” section.

Check Agents

Once you have selected the host, continue by clicking “Check Agent.”

Install Wizard

Once the agent has checked-in successfully, you can finish the process by inviting any users who need access to DPM in the last step.

If you have any problem with the agent install, do not hesitate to contact us by clicking the button in the bottom right corner of the application.

Enabling PERFORMANCE_SCHEMA and pg_stat_statements

See below for information on enabling the PERFORMANCE_SCHEMA or pg_stat_statements on your RDS instance.


You can enable the PERFORMANCE_SCHEMA in a regular MySQL server by adding the following line to your my.cnf configuration file under the [mysqld] section:


In the case of an Amazon RDS or Aurora instance follow these instructions instead:

  • Create a new custom DB Parameter Group in the RDS Dashboard, or modify an existing one.
  • Set option performance_schema = 1
  • Apply the parameter group.

In either case (self-hosted or RDS/Aurora) you’ll need to restart the server/instance for the changes to take effect.

The statements_digest and events_statements_history_long consumers need to be enabled:

UPDATE performance_schema.setup_consumers SET enabled = 'YES' WHERE name in ('statements_digest', 'events_statements_history_long');

Note that if you enable the consumers and restart your server they may no longer be enabled upon restart. To ensure this setting persists, add:


to your my.cnf file.

When using Amazon RDS or Aurora this option cannot be set via parameter group and cannot be persisted between restarts. However, the DPM agent can automatically enable these consumers if it detects that they are not enabled. To enable this setting, you can select “Force Off Host Samples” in an Environment’s Query Data Settings page. Alternatively, you can add the following options to your DPM vc-mysql-metrics.conf configuration file and restart your agents:

    "force-offhost-digests": "true",
    "force-offhost-samples": "true"

You will need to create the file if it does not exist.

The DPM user will need permission to update the performance_schema.setup_consumers table:

GRANT UPDATE ON performance_schema.setup_consumers TO vividcortex@'%'; 

More information about configuration files, including correct JSON formatting, is available here.

Enabling pg_stat_statements on PostgreSQL

You can enable the pg_stat_statements extension in a regular PostgreSQL server by installing the postgresql-contrib package (if not already present) then adding the following entries to your postgres.conf configuration file:

shared_preload_libraries = pg_stat_statements
track_activity_query_size = 4096
pg_stat_statements.track = ALL

The first line is required to make the extension available in the server, the second one is recommended if you have long queries, and the third one is used to track statements inside stored procedures.

In the case of an Amazon RDS instance follow these instructions instead:

  • Create a new custom DB Parameter Group in the RDS Dashboard, or modify an existing one.
  • Set an option for each of the settings discussed above.
  • Apply the parameter group.

The last step, in both cases, is to restart the server/instance then login and run the statement CREATE EXTENSION pg_stat_statements; on the database you want the monitoring user to connect to. The user assigned to DPM must have access to this table; you can verify this by running

SELECT COUNT(*) FROM pg_stat_statements;

as the user you have created for use with DPM. If this does not return successfully, it is likely that pg_stat_statements does not exist on the database the DPM user is connected to, or the DPM user is not a SUPERUSER; run CREATE EXTENSION pg_stat_statements on that database and ensure the user privileges are correct.

Amazon CloudWatch

We support downloading metrics from Amazon CloudWatch for your RDS or Aurora instance. This allows you to see system metrics, such as CPU and memory utilization, alongside your query data; this provides critical pieces of information necessary for diagnosing database issues. The list of metrics we collect from CloudWatch is here.

To enable integration, you need to provide appropriate access to your AWS account. The agent must be running in the same AWS account as the database. There are three ways to provide access:

  • Using the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • Using the /root/.aws/credentials file
  • Assigning the appropriate role to the instance running the DPM agent

Create a user which as the appropriate role (below) assigned. Provide credentials for that user either using the environment variables or credentials file. If providing credentials using the /root/.aws/credentials file, its contents look like this:


(The file must be in /root/, as that is the user which runs the DPM software.)

The AWS managed CloudWatchReadOnlyAccess and AmazonRDSReadOnlyAccess policies work, so make the user a member of a group that implements both of those. We strongly recommend using these managed policies, as they are future-proof and easier to implement.

If you opt to create a custom policy, it will need to include the following:

 "Version": "2012-10-17",

Note for proxy users: If you have installed the agent on an EC2 instance and are providing access to CloudWatch through an IAM role AND are using a proxy set via a system environment variable, you will need to exclude requests to the AWS metadata service. You can do this by setting the environment variable NO_PROXY to (the address of instance metadata information), with export NO_PROXY=

You should see CloudWatch metrics appear on your environment Summary page under the section “How healthy are the resources?” if the setup is correct. You will also begin to see data in the two CloudWatch dashboards, under Charts.