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 for PostgreSQL or MySQL
  • You are monitoring Amazon Aurora for PostgreSQL or MySQL
  • You otherwise do not have direct access to the server running the database.
  • You use encrypted connections or connect to your database over TLS

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 VividCortex

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 VividCortex 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 VividCortex to use, you should do that now. Select “Create User”.

MySQL

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.”

PostgreSQL

For all versions of PostgreSQL (including Amazon RDS), 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, 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 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 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.

Enabling PERFORMANCE_SCHEMA on MySQL

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:

performance_schema

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:

performance-schema-consumer-events-statements-current=ON
performance-schema-consumer-events-statements-history-long=ON

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 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. 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 VividCortex 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:

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

(The file must be in /root/, as that is the user which runs the VividCortex 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",
 "Statement":[{
        "Effect":"Allow",
        "Action":[
            "cloudwatch:GetMetricStatistics",
            "cloudwatch:ListMetrics",
            "rds:DescribeDBInstances",
            "rds:DescribeDBClusters",
            "rds:DescribeDBLogFiles",
            "rds:DownloadDBLogFilePortion",
            "logs:GetLogEvents"
        ],
        "Resource":"*"
     }  
 ]
}

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.