What Does It Do?
docker-alertd monitors docker containers on a host machine and sends alerts via email when usage limits have been breached.
Currently, alerts can be sent based on:
- Container existence (regardless of running state)
- Running state (running or existed)
- Memory usage (in MB)
- CPU Usage (as a percentage)
- Minimum Process running in container
Step 1: Install
Method: Build from source
Assuming that you already have
go installed on your machine, you can just
go get it.
go get github.com/deltaskelta/docker-alertd
If you would like to download a pre-compiled binary, head to the release downloads
Step 2: Make a Configuration File
Docker-Alertd needs a configuration file in order to run, it will search the directory
which contains the binary, and the home directory for a config file automatically. A
special config file location can be specified with the
A base config file can be generated with the command:
docker-alertd initconfig -d /path/to/config/location/
--- # The duration and interations settings, if omitted, have a default value of 100ms between # docker API calls and an indefinite number of iterations which will run the monitor forever #duration: 100 # duration in ms between docker API calls #iterations: 0 # number of iterations to run # 'containers' is an array of dictionaries that each contain the name of a container to # monitor, and the metrics which it should be monitored by. If there are no metrics # present, then it will just be monitored to make sure that is is currently up. # This will monitor only that the container exists, running or not... # containers: # - name: mycontainer containers: - name: container1 expectedRunning: true - name: container2 expectedRunning: true maxCpu: 20 maxMem: 20 minProcs: 4 # If email settings are present and active, then email alerts will be sent when an alert # is triggered. emailSettings: active: true smtp: smtp.someserver.com password: s00p3rS33cret port: 587 from: email@example.com subject: "DOCKER_ALERTD" to: - firstname.lastname@example.org
duration: the duration to wait between docker engine API calls.
iterations: the number of iterations that docker-alertd should run (0 = run forever)
name: the container name or ID
maxCpu: the maximum cpu usage threshold (as a percentage), if the container uses more
CPU, an alert will be triggered.
maxMem: the maximum memory usage threshold (in MB). If the container uses more system
memory than this, an alert will be triggered.
minProcs: the minimum number of running processes (PID's) in the container. If a the
number of running processes dips below this level (when a process fails), an alert will
active: whether email settings are active or not
smtp: the smtp server to connect to
password: the password to use for smtp authentication
port: the port to connect to the smtp server
from: the email address to send from
subject: the subject line of emails sent
to: an array of email addresses to send the alerts to
webhookURL: the webhookURL provided by slack after you authorize an app on a slack
channel. See slack apps
Step 3: Run the program
docker-alertd is in your system path, and the config file is in the home
directory or the same directory as the binary...
if the binary is not on your
$PATH then you will have to pass absolute paths.
$ /path/to/binary/docker-alertd --config ~/path/to/configuration/file/.docker-alertd.yaml
This will start the program and log the output to stdout. It can be stopped with CTRL-C.
2017/09/18 12:11:44 starting docker-alertd ------------------------------ 2017/09/18 12:11:44 ALERT: 2017/09/18 12:11:44 container1: Existence check failure: Error: No such container: container1 2017/09/18 12:11:44 container2: Existence check failure: Error: No such container: container2 ...
Step 4. Set up as a background process (optional)
If you wish to have docker-alertd run as a background process, it needs to be setup as a background process as per your operating system.
As A Systemd Service (for Linux systems with systemd)
With Launchd (MacOS)
With Sys V Init (various Linux systems without systemd)
Refer to this Sys V Init tutorial
If you want to run
docker-alertd from within Docker, you can do that. This requires
mounting the docker socket into the container which comes with security risks because the
container has access to the docker socket and therefore if it was compromised, it would
have root access on the system google - mounting docker socket security.
That being said if you decide it is something you want to do in development or in a controlled production environment, you can use the image on the docker registry.
pull the image frm the registry
docker pull deltaskelta/docker-alertd #or if you want to build your own tagged image, clone the repo and run #docker build -t [your-tag] .
run the command to get a config file printed to stdout. You must save it, modify it to fit
your needs, and then mount it into the container that will run
go-wrapper run is equivalient to
docker-alertd if the binary was installed
normally, so all of
docker-alertds normal commands will follow
docker run --rm deltaskelta/docker-alertd go-wrapper run initconfig --stdout
and then run the app with the mounted config file and the mounted docker socket.
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v ~/.docker-aled.yaml:/root/.docker-alertd.yaml deltaskelta/docker-alertd
Testing Alert Authentication
Docker-Alertd comes with a
testalert command which will search for a nonexistant
container name and send an alert to the appropriate places, use this for testing that
smtp or other authentication settings are correct