How to Upgrade Your Legacy Metrics Agent

As of 8 April 2019, all new metrics agent installations use our Prometheus-based metrics agent. This new agent is a lightweight, Prometheus-compatible monitoring agent that collects Droplet-level system metrics and reports them under the DigitalOcean Monitoring section.

As of 8 July 2019, we deprecated the legacy metrics agent. It was the monitoring agent used before we adopted the Prometheus-based agent. The legacy agent doesn’t support our newer metrics and also uses more system resources. Droplets still using this agent no longer show extended metrics in the DigitalOcean Control Panel or API.

Upgrading to the Prometheus-based agent ensures that you continue to receive extended metrics such as disk I/O, bandwidth, and CPU utilization. The newer agent also offers improved stability, lower resource usage, and compatibility with current monitoring features.

If you do not upgrade your metrics agent, your Droplet stops receiving extended metrics. This reduces visibility into resource usage and may interfere with your alerting and monitoring setup.

Check If Your Using the Legacy Agent

Before upgrading your metrics agent, check if your Droplet is still using the legacy agent by running the following command:

ps aux | grep do-agent

If the output includes /opt/digitalocean/bin/do-agent, you’re using the Prometheus-based agent. If it shows /usr/bin/droplet-agent, another path without Prometheus references, or returns no output, you’re likely using the legacy agent and need to upgrade your agent, or the agent is not running.

Alternatively, you can run the following command to check the installed agent version:

/opt/digitalocean/bin/do-agent --version

If this command fails or returns a version number below 3.x, you’re likely using the legacy agent and should upgrade your agent.

Upgrade Your Legacy Metrics Agent to the New Agent

To upgrade your legacy metrics agent to our Prometheus-based metrics agent, uninstall the legacy metrics agent. After removing the legacy metrics agent, install the Prometheus-based metrics agent by downloading the installation script, inspecting it, and running it manually.

If you want to upgrade multiple Droplets at once, use the upgrade-droplets.sh script provided in the do-agent GitHub repository. You need an SSH key and a DigitalOcean API token. Alternatively, an Ansible-based batch upgrade is available on Ansible Galaxy.

After upgrading the legacy agent, verify if the installation was successful. If upgrading your metrics agent fails these checks, see the do-agent GitHub issues page for community-reported solutions or open a support ticket.