Goplum

Goplum is an extensible monitoring and alerting daemon designed for personal infrastructure and small businesses. It can monitor websites and APIs, and send alerts by text message if they go down.

Getting started

The easiest way to run Goplum is via Docker. It doesn’t require any special privileges or settings, you just need to provide a config file to it at /goplum.conf.

Running it via the command line:

docker run -d --restart always -v /path/to/my/goplum.conf:/goplum.conf csmith/goplum

Or using Docker Compose:

version: "3.8"

services:
  goplum:
    image: csmith/goplum
    volumes:
      - ./goplum.conf:/goplum.conf
    restart: always

Configuration

Goplum’s configuration contains an optional defaults section, a list of alerts, and a list of checks. A simple example might look like this:

defaults {
  # Change the default interval for all checks to 10 second, rather than
  # Goplum's normal default of 30 seconds:
  interval = 10s
}

alert twilio.sms "text" {
  sid = "sid"
  token = "token"
  from = "+01 867 5309"
  to = "+01 867 5309"
}

check http.get "Example" {
  url = "https://www.example.com/"
}

This defines one check - of type http.get that will run every 30 seconds (the default interval specified in the "defaults" block). If the check starts failing, all the defined alerts will be triggered — in this case sending a text message via Twilio.

Each check and alert has a name, which is used to refer to it in the config and in messages, and a type. The type consists of the name of a plugin, a period, and then the type of check or alert from that plugin. Some checks and alerts take parameters, which are specified as key = value assignments within the block, one per line.

Checks have four additional settings. These can be changed globally by putting them in the "defaults" section. If they’re not specified then Goplum’s built-in defaults will be used:

interval

The time after which the check is repeated, for example 20s for 20 seconds, 10m for 10 minutes, or 7h for 7 hours. Global default: 30 seconds.

alerts

A list of alert names which should be triggered when the service changes state. The wildcard '*' may be used anywhere to match any number of characters. Note that an empty array is treated the same as a missing option, so default settings will be used; to disable alerts use ["-"]. Global default: ["*"] (all alerts).

failing_threshold

The number of times a check must fail in a row before the service is considered failing. This allows you to ignore brief, transient problems that may occur between your monitoring location and the service itself, or very brief outages such as webserver restarts. Global default: 2.

good_threshold

The number of times a check must pass in a row before the service is considered up. This prevents alert noise if a check occasionally passes for some reason. Global default: 2.

Data types

The following data types can be used in config files:

Strings

Represented as double quoted text, e.g. "This is a test".

The character \ may be used as an escape character, e.g.: "Bob said:\n\t\"Hello\"".

Durations

One or more integer numbers suffixed with units, e.g. 1d5h.

Valid units are:

• s - seconds

• m - minutes

• h - hours

• d - days (exactly 24 hours, regardless of calendar/DST changes)

• w - week (exactly 7 days)

Integers

Sequence of digits in base 10, e.g. 123456

Floats

Sequence of digits in base 10 with exactly one decimal point e.g. 1.234, .1 or 1.

Lists of strings

Individual strings contained in square brackets, separated by commas, e.g. ["foo", "bar"]. A single trailing comma is allowed e.g. ["foo", "bar",].

Bundled plugins

All checks and alerts in Goplum are implemented as plugins. The following are maintained in this repository and are available by default in the Docker image:

http

The HTTP plugin provides checks for HTTP services, and HTTP-based alerts.

Check: http.get

check http.get "example" {
  url = "https://www.example.com/"
  content = "Example Domain"
  certificate_validity = 10d
}

Sends a HTTP GET request to the given URL. The check passes if a response is received with an error code less than 400.

If the content parameter is specified then the response body must contain the exact string.

If the certificate_validity parameter is specified, then the connection must have been made over TLS, and the returned certificate must be valid for at least the given duration from now. (An expired or untrusted certificate will cause a failure regardless of this setting.)

Alert: http.webhook

alert http.webhook "example" {
  url = "https://www.example.com/incoming"
}

Sends alerts as a POST request to the given webhook URL with a JSON payload:

{
  "text": "Check 'Testing' is now good, was failing.",
  "name": "Testing",
  "type": "debug.random",
  "config": {
    "percent_good": 0.8
  },
  "last_result": {
    "state": "failing",
    "time": "2020-09-17T17:55:02.224973486+01:00",
    "detail": "Random value 0.813640 greater than percent_good 0.800000"
  },
  "previous_state": "failing",
  "new_state": "good"
}

network

The network plugin provides checks for low-level network services.

Check: network.connect

check network.connect "example" {
  address = "hostname:1234"
  network = "tcp6"
}

Attempts to open a network connection to the given address. Addresses must be in the form "host:port", "host%zone:port", "[host]:port" or "[host%zone]:port".

By default, connection attempts will be made over TCP (IPv6 or IPv4 using Fast Fallback). If the network parameter is included then connection attempts will be limited to that network. Valid options are: "tcp", "tcp4", "tcp6", "udp", "udp4", "udp6".

pushover

The pushover plugin sends alerts as push notifications via Pushover.

Alert: pushover.message

alert pushover.message "example" {
    token = "application-token"
    key = "user-or-group-key"
    devices = ["iphone", "nexus17"]
    failing {
        priority = 2
        sound = "siren"
        retry = 30s
        expire = 1h
    }
    recovering {
        priority = 1
        sound = "bugle"
    }
}

Sends a push notification via Pushover. The token and key values are required: token is an application key (you will need to create one for your goplum install via the Pushover website), and key is the user or group key you wish to send the alert to.

Optionally you can limit the alert to a specific device or devices by passing their names in the devices option.

You can configure sounds and priorities for both failing and recovering alerts by using the appropriate blocks. For emergency alerts (priority 2), you must also specify how often the alert is retried (minimum: 30s), and after how long it will stop (maximum: 3h).

If the priority is not set, or the blocks are omitted entirely, the alerts are sent as priority 0. If sounds are not set then the default sounds configured in the Pushover app will be used.

slack

The slack plugin provides alerts that send messages to Slack channels.

Alert: slack.message

alert slack.message "example" {
  url = "https://hooks.slack.com/services/XXXXXXXXX/00000000000/abcdefghijklmnopqrstuvwxyz"
}

Sends a Slack message via a Slack incoming webhook URL. To enable incoming webhooks you will need to create a Slack app in your workspace, enable the "Incoming Webhooks" feature, and then create a webhook for the channel you want messages to be displayed in.

twilio

The twilio plugin provides alerts that use the Twilio API.

Alert: twilio.sms

alert twilio.sms "example" {
  sid = "twilio sid"
  token = "twilio token"
  from = "+01 867 5309"
  to = "+01 867 5309"
}

Sends SMS alerts using the Twilio API. You must have a funded Twilio account, and configure the SID, Token, and From/To phone numbers.

debug

The debug plugin provides checks and alerts for testing and development purposes.

Check: debug.random

check debug.random "example" {
  percent_good = 0.8
}

Passes or fails at random. If the percent_good parameter is specified then checks will pass with that probability (i.e. a value of 0.8 means a check has an 80% chance to pass).

Alert: debug.sysout

alert debug.sysout "example" {}

Prints alerts to system out, prefixed with 'DEBUG ALERT'.

Plugin API

Goplum is designed to be easily extensible. Plugins must have a main package which contains a function named "Plum" that returns an implementation of goplum.Plugin. They are then compiled with the -buildtype=plugin flag to create a shared library.

The Docker image loads plugins recursively from the /plugins directory, allowing you to mount custom folders if you wish to supply your own plugins.

Note that the Go plugin loader does not work on Windows. For Windows-based development, the goplumdev command hardcodes plugins, skipping the loader.