Off-Host Installation

In off-host monitoring, the agent is installed on any compatible host, and connects to the monitored server over the network. This is necessary in cases such as Amazon RDS or Aurora, where the agent cannot be installed on the target host itself. You can monitor many remote hosts with a single supervisor on a single operating-system host of your choice.

As the agent is off-host, it cannot observe queries by capturing TCP traffic. Instead, it must rely on the target database’s built-in tools that expose query information, such as MySQL’s PERFORMANCE_SCHEMA and PostgreSQL’s pg_stat_statements.

Make sure you have the respective extension enabled in the server you want to monitor. Please see the Enabling PERFORMANCE_SCHEMA and pg_stat_statements section below.

Installing VividCortex

On the Inventory page, begin by opening the wizard, either by clicking “Setup your first host” if this is the first time you are adding a host, or “Add New Host” if it is not.

Once the wizard has opened, select “Off-Host,” and then select whether you will be monitoring a MySQL or PostgreSQL instance.

Set Credentials

On the next screen, enter the address of the service you wish to monitor, as well as the credentials for the user that VividCortex will use to connect to the database.

Install Wizard

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

Create User

This step in the installation is the one that differs the most for each database technology so follow the appropriate section for you below.


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 (including Amazon RDS for all non-EOL versions), 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 SUPERUSER (or rds_superuser) privilege to see the query text for other users.

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, VividCortex 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 VividCortex 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 below. 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

Share with your team

Once the agent has checked-in successfully, you can finish the process by inviting any users who need access to VividCortex 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 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 both cases you’ll need to restart the server/instance for the changes to take effect.

For MySQL (including Amazon RDS and Aurora for MySQL version 5.6.14 or newer), the statements_digest consumer needs to be enabled for query metrics to work:

UPDATE performance_schema.setup_consumers SET enabled = 'YES' WHERE name = 'statements_digest';

If you want to receive query samples, the events_statements_current and events_statements_history_long consumers need to be enabled as well:

UPDATE performance_schema.setup_consumers SET enabled = 'YES' WHERE name IN ('events_statements_current', '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 thus cannot be persisted between restarts by Amazon. However, the VividCortex agent can automatically enable these consumers if it detects that they are not enabled. To enable this setting, contact Support or add the following options to your VividCortex 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 VividCortex 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 = 2048
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 VividCortex 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 VividCortex. If this does not return successfully, it is likely that pg_stat_statements does not exist on the database the VividCortex user is connected to, or the VividCortex 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 instance.

To enable integration of CloudWatch metrics, the only thing you need to do is provide credentials (access keys) to your AWS account. You can use an existing user or, preferably, create a custom one for this. In terms of security, 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 be specified to include the following:

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

The access keys can be provided through environment variables (AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY) or via the /root/.aws/credentials file, whose contents look like this:


This is exactly the same file you’d already have if you were using AWS’s command line tools. For this reason, if the agent is running inside an EC2 instance, we may be able to fetch CloudWatch metrics automatically, with no action required, because we may already be authorized by the instance’s role. You may want to search for metrics bearing the aws suffix in the Metrics dashboard before following the setup instructions from above.