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, 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 from the monitored server’s network interface. 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 - see Enabling PERFORMANCE_SCHEMA and pg_stat_statements section below. Note that there is no off-host support for monitoring queries for MongoDB or Redis because they do not provide a similar way to examine running queries.

A step-by-step wizard will guide you through the process the first time you log into the application. If you would like to restart the installation wizard, or to add additional hosts in the future, you can do that from the Hosts List at any time. If you have any issues or questions during installation, do not hesitate to contact us by clicking the button in the lower right of your screen to talk to an engineer.

Installation

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.

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

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 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_history_long consumer needs to be enabled as well:

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

Note that if you enable this consumer and restart your server/instance it may no longer be enabled upon restart. To ensure this setting persists add:

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

to your my.cnf file or as an another option in the Parameter Group you’re using with your RDS instance.

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 all the database(s) you want the monitoring user to connect to.

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 policy works, so make the user member of a group that implements it. The minimum set we require, though, is specified in this custom policy:

{
 "Version": "2012-10-17",
 "Statement":[{
        "Effect":"Allow",
        "Action":["cloudwatch:GetMetricStatistics","cloudwatch:ListMetrics"],
        "Resource":"*",
        "Condition":{
            "Bool":{
            "aws:SecureTransport":"true"
            }
        }
     }  
 ]
}

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

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

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.