goplum

= 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 JSON
config file to it at `/config.json`.

Running it via the command line:

[source]
----
docker run -d --restart always -v /path/to/my/config.json:/config.json csmith/goplum
----

Or using Docker Compose:

[source,yaml]
----
version: "3.8"

services:
  goplum:
    image: csmith/goplum
    volumes:
      - ./config.json:/config.json
    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:

[source,json]
----
{
  "defaults": {
    "alerts": ["*"],
    "interval": "30s",
    "good_threshold": 3,
    "failing_threshold": 2
  },
  "alerts": [
    {
      "name": "text",
      "type": "twilio.sms",
      "params": {
        "sid": "sid",
        "token": "token",
        "from": "+01 867 5309",
        "to": "+01 867 5309"
      }
    }
  ],
  "checks": [
    {
      "name": "Example",
      "type": "http.get",
      "params": {
        "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 two consecutive checks fail, all the
defined alerts will be triggered -- in this case sending a text message via Twilio.
If the check is failing and three consecutive checks pass, it will be considered up again.

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 given in the
"params" field.

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. 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.

== 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

[source,json]
----
{
  "name": "example",
  "type": "http.get",
  "params": {
    "url": "https://www.example.com/",
    "content": "I'm Feeling Lucky",
    "certificate": {
      "valid_for": "48h"
    }
  }
}
----

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.valid_for` 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

[source,json]
----
{
  "name": "example",
  "type": "http.webhook",
  "params": {
    "url": "https://www.example.com/"
  }
}
----

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

[source,json]
----
{
  "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"
}
----

=== slack

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

==== Alert: slack.message

[source,json]
----
{
  "name": "example",
  "type": "slack.message",
  "params": {
    "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

[source,json]
----
{
  "name": "example",
  "type": "twilio.sms",
  "params": {
    "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

[source,json]
----
{
  "name": "example",
  "type": "debug.random",
  "params": {
    "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

[source,json]
----
{
  "name": "example",
  "type": "debug.sysout"
}
----

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.