How To Install and Use the DigitalOcean Agent for Monitoring
Introduction
DigitalOcean Monitoring tracks 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. The Agent also allows you to set up alert policies and notifications.
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, DigitalOcean Monitoring features like alert policies are available, and 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. Fedora is supported if the Agent is installed manually with the installation script.
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. Since the Agent only uses the ports for outbound data, you can safely run a web server without interference.
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 and other DigitalOcean Monitoring features, 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.
If you are using the DigitalOcean API to create Droplets, you can set the monitoring attribute to true in the creation parameters to automatically install the Agent on the Droplet during creation. The Droplet creation section of the API documentation contains additional details.
Installing the Agent Manually
You can also install the Agent manually. There is an installation script available that automatically detects the client operating system and configures repositories to install the agent. If you are uncomfortable running an installation script, you can set up your repositories manually.
With an Installation Script
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 sudo access:
- ssh root@droplet_IP_address
Once connected, to install and enable the 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 sudo user.
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.
Configuring Repositories Manually
You can also add the repositories and install the package manually if you prefer.
Ubuntu and Debian
To add the Agent repository, create and open a file in the /etc/apt/sources.list.d directory with sudo privileges:
- sudo nano /etc/apt/sources.list.d/digitalocean-agent.list
Inside, add the following line:
deb https://repos.sonar.digitalocean.com/apt main main
Save and close the file.
Next, add the DigitalOcean key to apt by typing:
- curl https://repos.sonar.digitalocean.com/sonar-agent.asc | sudo apt-key add -
Now you can update the repository package index and install the Agent by typing:
- sudo apt-get update
- sudo apt-get install do-agent
The agent should now be installed and running.
CentOS
On CentOS, create and open a repository definition file with sudo privileges:
- sudo vi /etc/yum.repos.d/digitalocean-agent.repo
Inside, paste the following configuration:
[sonar]
name=do agent
baseurl=https://repos.sonar.digitalocean.com/yum/$basearch
failovermethod=priority
enabled=1
gpgcheck=1
gpgkey=https://repos.sonar.digitalocean.com/sonar-agent.asc
Import the DigitalOcean key by typing:
- sudo rpm --import https://repos.sonar.digitalocean.com/sonar-agent.asc
Now, you can install the Agent by typing:
- sudo yum install do-agent
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 Create Alert Policies and Notifications
To set up alert policies to receive notifications when resource usage goes beyond certain boundaries, click on the Monitoring tab at the top of the control panel. Follow our guide on setting up alert policies to learn more.
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.
Conclusion
The DigitalOcean Agent expands the coverage of Droplet Graphs to provide additional information about your server's performance and resource usage and enables alert policies so that you can receive timely notifications about usage changes. To learn more about the DigitalOcean Monitoring, check out these guides:
52 Comments