Checkup

<img src="https://i.imgur.com/UWhSoQj.png" width="450" alt="Checkup">

Checkup is distributed, lock-free, self-hosted health checks and status pages, written in Go.

It features an elegant, minimalistic CLI and an idiomatic Go library. They are completely interoperable and their configuration is beautifully symmetric.

Checkup was created by Matt Holt, author of the Caddy web server. It is maintained and sponsored by Sourcegraph. If you'd like to dive into the source, you can start here.

This tool is a work-in-progress. Please use liberally (with discretion) and report any bugs!

Recent changes

Due to recent development, some breaking changes have been introduced:

• providers: the json config field provider was renamed to type for consistency,
• notifiers: the json config field name was renamed to type for consistency,
• sql: by default the sqlite storage engine is disabled (needs build with -tags sql to enable),
• sql: storage engine is deprecated in favor of new storage engines postgres, mysql, sqlite3
• mailgun: the to parameter now takes a list of e-mail addresses (was a single recipient)
• LOGGING IS NOT SWALLOWED ANYMORE, DON'T PARSE checkup OUTPUT IN SCRIPTS
• default for status page config has been set to local source (use with checkup serve)

If you want to build the latest version, it's best to run:

• make build - builds checkup with mysql and postgresql support,
• make build-sqlite3 - builds checkup with additional sqlite3 support

The resulting binary will be placed into builds/checkup.

Intro

Checkup can be customized to check up on any of your sites or services at any time, from any infrastructure, using any storage provider of your choice (assuming an integration exists for your storage provider). The status page can be customized to your liking since you can do your checks however you want. The status page is also mobile-responsive.

Checkup currently supports these checkers:

• HTTP
• TCP (+TLS)
• DNS
• TLS

Checkup implements these storage providers:

• Amazon S3
• Local file system
• GitHub
• MySQL
• PostgreSQL
• SQLite3
• Azure Application Insights

Currently the status page does not support SQL or Azure Application Insights storage back-ends.

Checkup can even send notifications through your service of choice (if an integration exists).

How it Works

There are 3 components:

1. Storage. You set up storage space for the results of the checks.
2. Checks. You run checks on whatever endpoints you have as often as you want.
3. Status Page. You (or GitHub) host the status page.

Quick Start

Download Checkup for your platform and put it in your PATH, or install from source:

$ go get -u github.com/sourcegraph/checkup/cmd/checkup

You'll need Go 1.8 or newer. Verify it's installed properly:

$ checkup --help

Then follow these instructions to get started quickly with Checkup.

Create your Checkup config

You can configure Checkup entirely with a simple JSON document. You should configure storage and at least one checker. Here's the basic outline:

{
    "checkers": [
        // checker configurations go here
    ],

    "storage": {
        // storage configuration goes here
    },

    "notifiers": [
        // notifier configuration goes here
    ]
}

Save the checkup configuration file as checkup.json in your working directory.

We will show JSON samples below, to get you started. But please refer to the godoc for a comprehensive description of each type of checker, storage, and notifier you can configure!

Here are the configuration structures you can use, which are explained fully in the godoc. Only the required fields are shown, so consult the godoc for more.

HTTP Checker

godoc: check/http

{
    "type": "http",
    "endpoint_name": "Example HTTP",
    "endpoint_url": "http://www.example.com"
    // for more fields, see the godoc
}

TCP Checker

godoc: check/tcp

{
    "type": "tcp",
    "endpoint_name": "Example TCP",
    "endpoint_url": "example.com:80"
}

DNS Checkers

godoc: check/dns

{
    "type": "dns",
    "endpoint_name": "Example of endpoint_url looking up host.example.com",
    "endpoint_url": "ns.example.com:53",
    "hostname_fqdn": "host.example.com"
}

TLS Checkers

godoc: check/tls

{
    "type": "tls",
    "endpoint_name": "Example TLS Protocol Check",
    "endpoint_url": "www.example.com:443"
}

Exec Checkers

godoc: check/exec

The exec checker can run any command, and expects an zero-value exit code on success. Non-zero exit codes are considered errors. You can configure the check with "raise":"warning" if you want to consider a failing service as DEGRADED. Additional options available on godoc link above.

{
    "type": "exec",
    "name": "Example Exec Check",
    "command": "testdata/exec.sh"
}

Amazon S3 Storage

godoc: S3

{
    "type": "s3",
    "access_key_id": "<yours>",
    "secret_access_key": "<yours>",
    "bucket": "<yours>",
    "region": "us-east-1"
}

To serve files for your status page from S3, copy statuspage/config_s3.js over statuspage/config.js, and fill out the required public, read-only credentials.

File System Storage

godoc: FS

{
    "type": "fs",
    "dir": "/path/to/your/check_files"
}

GitHub Storage

godoc: GitHub

{
    "type": "github",
    "access_token": "some_api_access_token_with_repo_scope",
    "repository_owner": "owner",
    "repository_name": "repo",
    "committer_name": "Commiter Name",
    "committer_email": "you@example.com",
    "branch": "gh-pages",
    "dir": "updates",
    "commit_message_suffix": "[ci skip]"
}

• "dir" is a subdirectory within the repo to push all the check files
• "commit_message_suffix" is appended to each commit message (default: "[ci skip]", to remove set to " " (single space))

Setup instructions:

1. Create a repository,
2. Copy the contents of statuspage/ from this repo to the root of your new repo,
3. Update the URL in config.js to https://your-username.github.com/dir/,
4. Create updates/.gitkeep,
5. Enable GitHub Pages in your settings for your desired branch.

MySQL Storage

godoc: storage/mysql

A MySQL database can be configured as a storage backend.

Example configuration:

{
    "type": "mysql",
    "create": true,
    "dsn": "checkup:checkup@tcp(mysql-checkup-db:3306)/checkup"
}

When create is set to true, checkup will issue CREATE TABLE statements required for storage.

SQLite3 Storage (requires CGO to build, not available as a default)

godoc: storage/sqlite3

A SQLite3 database can be configured as a storage backend.

Example configuration:

{
    "type": "sqlite3",
    "create": true,
    "dsn": "/path/to/your/sqlite.db"
}

When create is set to true, checkup will issue CREATE TABLE statements required for storage.

PostgreSQL Storage

godoc: storage/postgres

A PostgreSQL database can be configured as a storage backend.

Example configuration:

{
    "type": "postgres",
    "dsn": "host=postgres-checkup-db user=checkup password=checkup dbname=checkup sslmode=disable"
}

When create is set to true, checkup will issue CREATE TABLE statements required for storage.

Azure Application Insights Storage

godoc: appinsights

Azure Application Insights can be used as a storage backend, enabling Checkup to be used as a source of custom availability tests and metrics. An example use case is documented here.

A sample storage configuration with retries enabled:

{
  "type": "appinsights",
  "test_location": "data center 1",
  "instrumentation_key": "11111111-1111-1111-1111-111111111111",
  "retry_interval": 1,
  "max_retries": 3,
  "tags": {
    "service": "front end",
    "product": "main web app"
  }
} 

The following keys are optional:

• test_location (default is Checkup Monitor)
• retry_interval (default is 0)
• max_retries (default is 0)
• timeout (defaults to 2 seconds if omitted or set to 0)
• tags

If retries are disabled, the plugin will wait up to timeout seconds to submit telemetry before closing.

When check results are sent to Application Insights, the following values are included in the logged telemetry:

• success is set to 1 if the check passes, 0 otherwise
• message is set to Up, Down, or Degraded
• duration is set to the averag