Advanced Installation

This page includes instructions for monitoring only specific servers on a host running multiple databases, as well as manual installation instructions and instructions on installing the Database Performance Monitor agent using Chef, Puppet, or Ansible.

Ignore Automatically Detected Servers

If you have multiple databases running on one host, the DPM agent will automatically detect and begin monitoring all of them. However, if you want to ignore some of those hosts, you can do so by changing the /etc/vividcortex/global.conf configuration file to include the option ignore-bindings, which is a comma-separated list of port:ip you want to ignore.

For example, you may have two database servers running on one host, with one listening on port 44000 and another on 44001. If you did not want to monitor the database listening on 44001, you would likely add "ignore-bindings":"0.0.0.0:44001,[::]:44001" to your global.conf file:

{
"api-token":"XYZ123...",
"ignore-bindings":"0.0.0.0:44001,[::]:44001",
...
}

The easiest way to identify the bindings is to look at the host you want to ignore on the Machines page in DPM and find the value(s) for listening on:

This is the value you will give to ignore-bindings. Restart the service, or wait ten minutes for the supervisor to refresh its list of monitored hosts.

Manually Specifying Hosts to Monitor

First, download and install DPM. You will need your API token, which you can find in the web application by clicking “Add New Host” and then “Containerized”:

curl https://download.vividcortex.com/install > install
sh install --token <API_TOKEN> --autostart --proxy=auto

To specify what database (or databases) to monitor, you will need the following: * the URI of your database (and any required TLS configuration options), and * a query capture method

Database URI

The connection URI for your database will be one of the following:

Database	URI syntax
MongoDB	`[cust_hostname=]mongo://user:pass@example0-shard-00-00-ream0.mongodb.net:27017/` or `[cust_hostname=]mongodb+srv://user:pass@example0-shard-00-00-ream0.mongodb.net:27017/` (When using `mongodb+srv`, DPM will connect to the first instance returned by DNS.)
MySQL	`[cust_hostname=]mysql://user:pass@0.0.0.0:port/`
PostgreSQL	`[cust_hostname=]postgres://user:pass@0.0.0.0:port/db`
Azure SQL & SQL Server	`[cust_hostname=]mssql://user:pass@0.0.0.0:port/db`
Redis	`[cust_hostname=]redis://:pass@0.0.0.0:port/`

Replace user, pass, and port with the DPM username, the password for that user, and the database listening port. For PostgreSQL and SQL Server, you may also need to specify the name of the database to connect to, db. The user and password cannot contain any of the URI reserved characters ( : / ? # [ ] @ % ). Any URI reserved characters will need to be percent encoded in the URI.

If the agent is installed on the same host as as the database and the capture method (see below) will be sniff, it is important to specify 0.0.0.0; this will instruct the agent to sniff all traffic to the entered port. If this is a MySQL server and skip_name_resolve is active, login permissions will be necessary for 127.0.0.1. If it is not active, it will likely be localhost but may be different.

cust_hostname= is optional but highly recommended; use it to specify a custom name for this database different from the one that would be automatically generated (the OS hostname). You can use this to give the database a human-readable name in DPM. An example would be report_server=mysql://vc_user:vc_pass@0.0.0.0:3306.

If your database requires secure connections, you can add the following options to the connection URI.

Database	Options	Description
MySQL	`sslenabled=true`	Enables TLS
	`sslca=<ca>`	`<ca>` is the path to a PEM encoded root certificate file on the agent host
	`sslkey=<key>`	`<key>` is the path to a PEM encoded key file on the agent host
	`sslcert=<cert>`	`<cert>` is the path to PEM encoded certificate file on the agent host
PostgreSQL	`sslenabled=true`	Enables TLS
	`sslmode=<mode>`	`<mode>` is one of the following options:
	`sslca=<ca>`	`<ca>` is the path to a PEM encoded root certificate file on the agent host
	`sslkey=<key>`	`<key>` is the path to a PEM encoded key file on the agent host
	`sslcert=<cert>`	`<cert>` is the path to PEM encoded certificate file on the agent host
	`sslmode=<mode>`	`require` - prevents the agent from attempting connection without TLS, if TLS fails `verify-ca` - agent checks that the root certificate is valid `verify-full` - agent checks that both the certificate is valid and the server’s hostname matches the certificate
MongoDB	`sslenabled=true`	Enables TLS
	`sslkey=<key>`	`<key>` is the path to a PEM encoded client certificate
Azure SQL & SQL Server	`sslenabled=true`	Enables TLS
	`sslca=<ca>`	`<ca>` is the file path that contains the public key certificate of the CA that signed the SQL Server certificate
	`sslmode=<mode>`	`require` - prevents the agent from attempting connection without TLS, if TLS fails `verify-ca` - agent checks that the root certificate is valid

A complete example of the above for MySQL would be my_hostname=mysql://user:pass@0.0.0.0:port/dbname?sslenabled=true&sslkey=...&sslcert=...&sslca=....

Query Capture Method

The capture method controls how the agent should attempt to monitor the database. This table describes the available capture methods for each database technology. Some database types have only one available capture method:

Database	Capture Method	Description
MySQL	`sniff`	Capture queries using TCP packet sniffing. Supported for on-host/local databases only. Recommended.
	`poll`	Capture queries using the `performance_schema`.
	`slow-log`	Capture queries using the MySQL slow query log. Supported for AWS RDS/Aurora databases only. Use only if the `performance_schema` cannot be enabled.
PostgreSQL	`sniff`	Capture queries using TCP packet sniffing. Supported for on-host/local databases only. Recommended.
	`poll`	Capture queries using `pg_stat_statements`.
MongoDB	`sniff`	Capture queries using TCP packet sniffing. Supported for on-host/local databases only.
	`slow-log`	Capture queries using the MongoDB activity log.
	`profiler`	Capture queries using the MongoDB db.profile collection.
Azure SQL & SQL Server	`query-cache`	Capture queries using the SQL Server query cache.
Redis	`sniff`	Capture queries using TCP packet sniffing. Supported for on-host/local databases only. DPM does not support hosted Redis-compatible databases, such as ElastiCache.
Vitess	`sniff`	Capture queries using TCP packet sniffing. Supported for on-host/local databases only. Recommended.
	`query-log`	Capture queries using the Vitess query log.

Create configuration file

Once you have the completed URI (with any options for secure connections) and a capture method, create /etc/vividcortex/vc-agent-007.conf and copy & paste the following, replacing <HOST URI> with the host URI. You can monitor multiple databases by specifying a comma-separated list of URIs.

{
    "use-drv-mongo": "false",
    "use-drv-mysql": "false",
    "use-drv-pgsql": "false",
    "use-drv-redis": "false",
    "drv-manual-query-capture": "CAPTURE METHOD",
    "drv-manual-host-uri": "<HOST URI>[,<HOST URI>][,...]"  
}

Save this file. If you previously installed DPM on this host using the off-host installation method, you will need to remove the option "host-discovery-limit":0 from your /etc/vividcortex/global.conf file.

Start the DPM service with service vividcortex start, /etc/init.d/vividcortex start, or whatever is appropriate for your system. Log-in to the DPM web application, and you should see your database(s) appear in the Inventory page.

Installing With Chef

We also provide a Chef cookbook that acts as an installation wrapper: github.com/VividCortex/chef-cookbook.

In order to use it, you must set the vividcortex['token'] attribute to your API token, and add its default recipe to your runlist. To find your API token, open the Add Hosts wizard and click “Containerized”; your API token will be displayed.

# Attribute example
{
    "vividcortex" => {
        "token" => "12345678901234567890123456789012"
    }
}

# Add it to your runlist:
{
    "run_list": ["recipe[vividcortex]"]
}

Installing From RPM Packages

We can provide an RPM repository with packages for your convenience. The RPM does not contain a complete set of agent binaries; instead it contains a stable version of the agent (and any plugins) which will upgrade and install itself.

Installing From Puppet

We also provide a Puppet manifest for installing the repo, at github.com/VividCortex/puppet. This installs the repo and the agent. It accepts various parameters such as your API token.

If you do not use a configuration management system such as Ansible, Chef, or Puppet to generate the /etc/vividcortex/global.conf file, you must generate it manually. The agent will not work without it, and the RPM installation will fail as a result. The configuration file must be created before installing the RPM.

To install the repository and then the agent, run the following commands:

rpm -Uvh https://download.vividcortex.com/linux/rpms/vividcortex-agents-1.7-815.amzn1.x86_64.rpm
yum install vividcortex-agents