How To Install and Use the DigitalOcean Agent for Additional Droplet Graphs
Droplet Graphs track your server resource usage over time. Some metrics, like bandwidth and disk I/O, can be easily measured or calculated from external tools. For a more complete picture, the DigitalOcean Agent can be installed on Droplets to provide metrics for memory and disk utilization and pass along information about the top consumers of CPU and memory on the system.
In this guide, we will introduce the DigitalOcean Agent and how it works. We will demonstrate how to install the Agent to collect these metrics. We will also show you how to completely remove the Agent if you no longer want enhanced metrics.
What is the DigitalOcean Agent?
The DigitalOcean Agent is an open-source Go utility that forwards basic metrics about your Droplet to the DigitalOcean metrics backend.
Without the Agent, Droplet Graphs display information about:
- Public and private bandwidth usage
- CPU activity
- Disk I/O
With the Agent, Droplet Graphs can additionally show:
- Memory Usage
- Disk Usage
- Top processes sorted by CPU and Memory
The Agent currently supports Ubuntu 14.04 and higher, CentOS 6 and higher, and Debian 8.
Visit the DigitalOcean Agent repository on GitHub to check out the code itself.
What Can the Agent Access?
The Agent service runs as an unprivileged user with access to only three directories:
/proc: Where the Agent collects data about the current state of the system
/var/opt: Where the Agent writes its authentication information
/opt/digitalocean: The binary's home directory
The Agent reports the top process names to the metrics endpoint. It does not report on environmental variables or process arguments to avoid exposing potentially sensitive information.
How Does the Agent Send Metrics?
The DigitalOcean Agent uses ports 80 and 443 for outgoing data. Inbound access is not required.
Port 80 is used to contact the DigitalOcean metadata service to obtain an authentication token. The Agent uses this token to authenticate to the metrics backend and encrypt its transmissions.
How To Enable the Agent
To enable extended metrics, the Agent must be installed on your Droplet. This can be done automatically during the Droplet Creation process or manually at any time.
Note: At this time, it is not possible to revert to the original graphs once the Agent has been enabled. This is a known issue that is currently being investigated.
Enabling the Agent During Droplet Creation
To install the Agent during Droplet creation, select the Monitoring checkbox in the additional options section of the creation page:
The Agent will be automatically installed and enabled during the Droplet creation process.
Installing the Agent Manually
An installation script is available to install the Agent manually. The script will add a repository to your system and use the native package manager to install the Agent. This simplifies package management tasks like upgrading or removing the Agent.
Log into your Droplet as
root or as a user with
- ssh root@droplet_IP_address
Once connected, to Agent immediately, you can download and execute the installation script by typing:
- curl -sSL https://agent.digitalocean.com/install.sh | sh
You may be prompted for your password if running as a
Note: If you would like to audit the script before installing, you can write it to disk first:
- curl -sSL https://agent.digitalocean.com/install.sh -o /tmp/install.sh
View the contents by typing:
- less /tmp/install.sh
When you are satisfied with the installation procedure, run the script by typing:
- sh /tmp/install.sh
The agent should now be installed and running.
How To View Enhanced Graphs
Once the Agent is enabled, visit the Graphs section of your Droplet's detail page:
The extended metrics will be available once your Agent checks in, which may take a moment:
Use the drop-down menu to adjust the time window displayed and mouse over the graphs to view detailed information.
How To Remove the Agent
If you no longer wish to use the Agent, you can remove the package using the native package manager.
For Ubuntu and Debian Droplets, type:
- sudo apt-get purge do-agent
For CentOS, type:
- sudo yum remove do-agent
The service will be stopped and the package will be removed from your System. If you wish to reinstall the agent later, you can do so with your package manager.
How To Remove the DigitalOcean Agent Repository
To remove the Agent repository from your Droplet, delete the repository configuration file.
On Ubuntu and Debian Droplets, type:
- sudo rm /etc/apt/sources.list.d/digitalocean-agent.list
On CentOS Droplets, type:
- sudo rm /etc/yum.repos.d/digitalocean-agent.repo
The Agent repository configuration will be removed from your Droplet.
The DigitalOcean Agent expands the coverage of Droplet Graphs to provide additional information about your server's performance and resource usage. To learn more about the metrics visualized by the Graphs section, check out our guide on Droplet Graphs.