Configuring VividCortex

The VividCortex agents retrieve their configuration, except for their API token, from the API. All of this configuration can be overridden locally if you wish. To see what configuration options are available for any 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 please refer to the configuration flags page.

Connection Credentials

Some of the VividCortex agents connect to a server or service to capture data. For example, the vc-mysql-metrics agent connects to MySQL. Naturally, you will need to provide credentials to instruct it how to connect (unless you’re running agents 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. Agents send events when they have trouble connecting to the host they’re 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, each agent reads two configuration files, in order:


Global configuration settings are overridden by the agent-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 agent’s --help output. For example, the vc-mysql-metrics agent 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 query samples can be found in the Query Samples documentation.

Required Network Settings

Agents must be able to reach the Internet to access our APIs. You need to permit access to port 443 on our API (DNS name and our download site (DNS name in your firewall. (Contact us for details if you need a static IP address instead.) Additionally, the agents need 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 agents support 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=
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 agents use 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": ""

Agent Upgrades

Agents are self-updating when we release new versions. The vc-agent-007 agent is responsible for upgrading agents, including itself. If you like, we can “pin” agents to a specific version for you. Contact Customer Support for more information.

When vc-agent-007 upgrades agents, 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 agents from an internal server, not from VividCortex’s download server. You can then maintain a mirror of internally.

Enterprise clients can select days and times when the agents 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.