Configuring VividCortex

The VividCortex agent retrieves its configuration, except for its API token, from the API. All of this configuration can be overridden locally if you wish. To see what configuration options are available for the agent as well as the current value set for each, execute the agent with the --help command-line option. For a more complete and comprehensive list of available configuration flags per agent plugin refer to the configuration flags page.

Connection Credentials

The the VividCortex agent connects to a server or service to capture data. Naturally, 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 VividCortex, a host is an operating system or a service, such as Linux or MySQL.

When such an agent starts up, it contacts the VividCortex APIs to retrieve its credentials. Note that we do not store any username, password, or other credentials locally in any configuration file, even temporarily. Instead, the credentials are stored in VividCortex’s secure cloud environment, strongly encrypted both in-flight and at-rest. You can read more about our security measures if you are interested in how this works.

VividCortex 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. The default credentials are not associated with any specific host, but they do have a host type. VividCortex also can associate a specific set of credentials to a specific host. These override the default environment-wide credentials.

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 Hosts Dashboard, 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 Dashboard to request a host restart. You should be able to see the agent restart as an event in the Events dashboard.
  • To troubleshoot credentials, look at the events in the Events dashboard. 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, the agent reads two configuration files, in order:

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

Global configuration settings are overridden by the plugin-specific file, and command-line options override those yet again. The config files are JSON. You can put any key-value pair into them that you can see in the plugin’s --help output. The plugin-specific configuration file may not exist in your installation, and you may need to create it.

For example, the vc-mysql-metrics plugin has a --fault-duration option, so you can configure that in the JSON in /etc/vividcortex/vc-mysql-metrics.conf if you like:

{
  "foo": "bar",
  "fault-duration": 60
}

However, again we recommend not including anything other than the minimum required configuration in the JSON configuration files, for ease of maintenance.

Configuration options available for limiting or disabling the capture of query samples, and potentially Personally Identifiable Information (PII), can be found in the Query Samples 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. (Contact us for details if you need a static IP address instead.) 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 VividCortex 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 VividCortex’s download server. You can then maintain a mirror of download.vividcortex.com internally.

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