Managing Hosts

Hosts are databases and the servers they are monitored from. Only databases, and servers installed but not monitoring a database, use a license.

Adding a Host

To add a host, see the installation instructions for details.

Naming and Replacing Hosts

When the agent is installed, it registers itself with the API. As part of this registration, it communicates the hostname and operating system of the host on which it is installed. The agent then uses this information when reporting collected metrics in order to identify the service being monitored.

By default, the agent combines the hostname and operating system to form the full name of the host and the identifier the agent will use. This is fine for most cases where the host operating system where the agents run will not change frequently. However, if the physical host where the agent runs is decomissioned and the agent is installed on a new host, the new data and old data will not be ‘tied together’ because it is seen as a new host.

To avoid this, you can override the default, application-given name of a host with your own name. This will allow you to start a new server later with the same name, and the application will see both servers as being identical. This allows the data to be continuous after the move. This is useful when the agent is running on servers that need to be reprovisioned and continue monitoring an off-host database instance without interruptions.

To enable this configuration, create a /etc/vividcortex/vc-agent-007.conf JSON file with the following format when first setting up the host that may later be reprovisioned:

  "hostname": "unique_os_hostname"

This will override the hostname to unique_os_hostname. When the agent combines hostname and operating system to identify a host, it will use that hostname. It must be a unique identifier, and does not have to be the actual hostname of the server. For example, you could use the name rds-monitor-1 for a host which monitors an RDS instance.

Next, install DPM on the server as usual, and set up monitoring through the UI.

Later, if you wish to move the agent from one host to another but continue to monitor the same remote database with no discontinuity in data, first shutdown the agent on the original host. On the new host, ensure that the vc-agent-007.conf file has the same hostname on the new server (rds-monitor-1 in the example above), and install DPM on the new server. The off-host agent and credential configuration will follow to the new server. There should be no visible changes in the UI. The migration would look like the agent simply restarted on the same host.

Host Tags

Learn more about applying tags to hosts, which makes it easy to select a group of hosts at once, in our Inventory documentation.

Deleting a Host

To remove a host, simply shut down the agent on the host. After a timeout of two hours, the host will no longer be shown, but it remains in the historical views if you wish to look at it in the past. If you’d like to remove a host and reclaim its license immediately, you can do so with the following steps:

  • Select the host in the Inventory, and click on the gear that appears to the right of its name. You will see a popup like the one below:

    Delete Host Popup

  • Check the box labeled “I know what I’m doing”, and click on the Delete button to confirm deletion. Once deleted a host will automatically be removed from your license count. The host’s historical data will remain, but restarting the agent will create a new host rather than reuse the existing one.

Once a host is deleted it’s also a good idea to uninstall DPM on that server.

You can also uninstall DPM and immediately delete the host from the command line with the following:

curl > install
sh install --delete

This will remove the DPM software from that host as well as permanently delete the host from the interface, which frees the license immediately. This is useful if you automate the provisioning and deprovisioning of hosts, since you do not need to log into the account to reclaim a license.


Your environment may have a configured limit on the number of hosts that can be active at any one time. This is represented by the number of licenses available in your account. To view the number of used and total licenses, go to the Settings page, and under “Organization Overview”, check Licenses.

When the agent starts up, if it tries to register a new host with our API and there are too many active hosts already, it will not succeed and won’t start fully. You’ll see a message in the vc-agent-007 log, similar to the following:

unable to register OS (retrying in 1m0s): maximum number of hosts exceeded;
terminate some and wait 2h, or contact VividCortex

The agent will continue to retry until the number of active registered hosts is smaller than your quota. If you’ve deactivated an old host you no longer want, it may continue to be counted as active for up to two hours, hence the instruction to wait for 2 hours. You can also delete the host (see above) to reclaim the license immediately.

Missing Hosts

If you’ve installed the agent on a host but you don’t see the host in your Inventory, please check the following:

  • Is the agent running and sending data to our APIs? If not, after a timeout the host will be considered to have gone away. Check the agent logs in /var/log/vividcortex/.
  • Does the time selector in the top-right corner of the app include a time range where the host was active?
  • Is the host within your quota? See the previous section.