The do-agent
extracts system metrics from
DigitalOcean Droplets and transmits them to the DigitalOcean
monitoring service. When the agent is initiated on a Droplet it
will automatically configure itself with the appropriate settings.
Flag | Option | Description |
---|---|---|
-log_syslog | bool | Log to syslog. |
-log_level | string | Sets the log level. [ INFO, ERROR, DEBUG ] Default=INFO |
-force_update | bool | force an agent update. |
-v | bool | Prints DigitalOcean Agent version. |
-h | bool | Prints do-agent usage information. |
Generally used during development and debugging.
Flag | Option | Description |
---|---|---|
DO_AGENT_AUTHENTICATION_URL | string | Override the authentication URL |
DO_AGENT_APPKEY | string | Override AppKey |
DO_AGENT_METRICS_URL | string | Override metrics URL |
DO_AGENT_DROPLET_ID | int64 | Override Droplet ID |
DO_AGENT_AUTHTOKEN | string | Override AuthToken |
DO_AGENT_UPDATE_URL | string | Override Update URL |
DO_AGENT_REPO_PATH | string | Override Local repository path |
DO_AGENT_PLUGIN_PATH | string | Override plugin directory path |
DO_AGENT_PROCFS_ROOT | string | Override location of /proc |
make build
sudo -u nobody ./do-agent <flags>
make test
echo "deb https://repos.sonar.digitalocean.com/apt main main" > /etc/apt/sources.list.d/sonar.list
curl https://repos.sonar.digitalocean.com/sonar-agent.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install do-agent
cat <'EOF' > /etc/yum.repos.d/DigitalOcean-Sonar.repo
[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
EOF
rpm --import https://repos.sonar.digitalocean.com/sonar-agent.asc
yum install do-agent
yum update do-agent
apt-get update && apt-get install --only-upgrade do-agent
sudo yum remove do-agent
sudo apt-get purge do-agent
dpkg -i do-agent_<version>_<build>.deb
rpm -Uvh do-agent-<version>_<build>.rpm
dpkg --remove do-agent
rpm -e do-agent
You can optionally run the Agent in Docker. To do so:
make docker
In order for the agent to report accurate metrics, you need to bind mount in
/proc inside the container:
docker run --rm \ -v /proc:/agent/proc:ro \ do-agent
do-agent
builds in a common set of metrics, and provides a plugin mechanism to
add additional metric collectors. Plugins are executable files that are placed
in the agent's plugin directory (see DO_AGENT_PLUGIN_PATH
). When do-agent
starts, it will find all executables in the plugin path and call them during
metric collection.
A collection agent must do two things:
- report metric configuration to stdout when a "config" argument is passed.
- report metric values to stdout when no argument is passed.
See plugins/test.sh
for a simple static plugin, in the form of a shell script.
Plugins may be written in any language, and must only know how to produce
serialized results in json
format.
When test.sh is run with "config" as the argument, it produces the following:
{
"definitions": {
"test": {
"type": 1,
"labels": {
"user": "foo"
},
"label_keys": ["timezone", "country"]
}
}
}
Definitions is a mapping of metric name to configuration. type
is an integer
type, compatible with the Prometheus client definition. The following types are
supported:
Type Value | Description |
---|---|
0 | Counter |
1 | Gauge |
Two types of labels are supported: fixed and dynamic. Fixed labels are specified
once in the metric definition and never specified in the metric value. In the
example above, there is a fixed label user:foo
. This label will be set on
all values of the metric.
The second type of label is a dynamic label. Dynamic labels have a fixed key
but the value is specified with every update of the metric. The example above
has two dynamic labels, with the keys timezone
and country
. The values
for these labels will be provided on each metric update.
When test.sh is run without any arguments, it produces the current value of the collected metrics. For example:
{
"metrics": {
"test": {
"value": 42.0,
"label_values": ["est", "usa"]
}
}
}
The (optional) label_values must correspond to the label_keys in the definition. If there were two label keys in the definition, then there must be exactly two label values in each metric update.
The do-agent
project makes use of the GitHub Flow
for contributions.
If you'd like to contribute to the project, please open an issue or find an existing issue that you'd like to take on. This ensures that efforts are not duplicated, and that a new feature aligns with the focus of the rest of the repository.
Once your suggestion has been submitted and discussed, please be sure that your code meets the following criteria:
- code is completely
gofmt
'd - new features or codepaths have appropriate test coverage
go test ./...
passesgo vet ./...
passesgolint ./...
returns no warnings, including documentation comment warnings
In addition, if this is your first time contributing to the do-agent
project,
add your name and email address to the
AUTHORS file
under the "Contributors" section using the format:
First Last <email@example.com>
.
First, to setup the project, ensure that $GOPATH
variable is pointing to an
existing directory, where all your Go code will be available.
After forking the repo on Github, run:
go get github.com/digitalocean/do-agent
cd $GOPATH/src/github.com/digitalocean/do-agent
git remote add my-fork <the url for your fork>
make test # ensure tests are passing
Push your changes to your fork:
git push -u master my-fork
Finally, submit a pull request for review!
If you discover a software bug, please feel free to report it by:
- Search through the existing issues to ensure that the bug hasn't already been filed.
- Open an issue for a new bug.