The Database Performance Monitor agent retrieves its configuration, except for its API token, from the API. However, any part of this configuration can be overridden locally.

Connection Credentials

The the DPM agent connects to a server or service to capture data. You will need to provide credentials to instruct it how to connect (unless you’re running the agent in a Heroku dyno, where we’ll fetch credentials automatically; see Installing For Heroku ). These credentials are associated with a host. In DPM, a host is an operating system or a service, such as Linux or MySQL.

When such an agent starts up, it contacts the DPM APIs to retrieve its credentials. Credentials are stored in DPM’s secure cloud environment, strongly encrypted both in-flight and at-rest.

DPM also supports a set of default credentials which are specific to a host type and are stored at the environment level. These are used as a fallback if a host doesn’t have specific credentials associated with it.

As a result, when the agent asks the API where it should connect to do its work, the API first looks for host-specific credentials, and then for default credentials for the host type if no specific ones are found.

The default credentials are appropriate to use when the credentials won’t vary from host to host. For example, “connect to localhost port 3306 with username X and password Y” might work everywhere in your environment. This is appropriate for default credentials. If you’re entering specific hostnames and ports, or usernames and passwords that won’t work on every host, you should probably use custom host-specific credentials.

To edit the credentials:

• When you set up your first host with the Add Hosts wizard, the credentials you enter will be stored as your environment-wide defaults.
• To edit default credentials, click on Settings, then Credentials under the “Environment Settings” section. Select the appropriate database type and enter the default credentials you wish to use.
• To edit a host’s custom credentials, select the host on the Inventory page, and edit its properties with the pop-up editor dialog by clicking the gear icon at the right of the screen.
• To switch a host from custom credentials to defaults or vice versa, edit the host’s settings as just mentioned, and then use the Agents page to request a host restart. You should be able to see the agent restart as an event in the Events page.
• To troubleshoot credentials, look at the events in the Events page. An agent sends events when it has trouble connecting to the host it’s instructed to contact. You can also look at the agent’s log file on the host where the agent runs. Log files can be found in /var/log/vividcortex/. Alternatively, log files can be accessed through the UI by visiting the Agents page, and clicking the gear icon at the far right for that agent.

Configuration Files

On each host, agents read two configuration files, in order (global settings are overridden by the agent-specific file; command-line options override both):

/etc/vividcortex/global.conf
/etc/vividcortex/<agent-name>.conf

For example, if monitoring a MongoDB database, you might have a /etc/vividcortex/global.conf file, a vc-os-metrics.conf file, and a vc-mongo-query.conf file. The global.conf file is read by every agent; the vc-os-metrics.conf will be read by the agent fetching operating system metrics, and vc-mongo-query.conf will be read by the MongoDB TCP agent. Note however that when using default settings, typically only a /etc/vividcortex/global.conf file is necessary and therefore is created automatically. You will need to create any other configuration files necessary if they do not exist.

The config files are JSON. When editing or creating a new configuration file, be sure to include the opening and closing { and }, and ensure that the options are comma-separated. For example, a file might look like the following:

{
  "disable-sampling":"false",
  "enable-explains":"false"
}

The API token found in the global.conf file grants access to your data, so it is secret and should be handled carefully; do not share it insecurely with others and avoid copy and pasting it whenever possible. When contacting DPM support do not include your API token in any sample files or API requests.

Options available for these configuration files are found throughout the documentation where relevant. For example, configuration options available for limiting or disabling the capture of query samples scan be found in the Query Samples documentation; configuring the behavior of certain Event types can be found in our Events documentation.

Required Network Settings

The agent must be able to reach the Internet to access our APIs. You need to permit access to port 443 on our API (DNS name app.vividcortex.com) and our download site (DNS name download.vividcortex.com) in your firewall. Additionally, the agent needs to be able to access Amazon’s S3 storage. This is used as a backup measure for time-series data, in case our API becomes unreachable for any reason.

The agent supports an HTTP proxy setting in the configuration file or the environment. The easiest way to do this is with the setting in the environment, as follows:

export http_proxy=http://url.to.your.proxy/
export https_proxy="${http_proxy}"
## Now use curl to download and execute the installation script as usual,
## making certain you use the same shell in which you set the variables.

This procedure will result in the curl command using the proxy to download the installation script. The installation script will write the proxy’s URL into the global configuration file so the agent uses the proxy to communicate with the DPM APIs.

If you need to, you can manually configure the proxy in the global configuration file. The file is /etc/vividcortex/global.conf and the resulting file should look like the following:

# cat /etc/vividcortex/global.conf
{
    "api-token": "<your token>",
    "proxy-uri": "http://url.to.your.proxy/"
}

Agent Upgrades

The agent is self-updating when we release new versions.

When the agent upgrades, it downloads new binaries from the URI indicated by its --cdn-uri option. If you wish, you can point this to an internal host so it downloads updates from an internal server, not from DPM’s download server. You can then maintain a mirror of download.vividcortex.com internally.

Premium clients can select days and times when the agent should download upgrades on a per-environment basis, using the Agents Maintenance Window feature. For more information about enabling this option, see the Environment Preferences documentation.