Documentation — Monitoror, unified monitoring wallboard

Quick access

Get started Download

Other resources

Configuration Guides Bug reports & Feature requests

Monitorable tiles

Azure DevOps GitHub GitLab HTTP Jenkins Ping Pingdom Port Travis CI

Utility tiles

Empty Group

Support Monitoror
Do you enjoy Monitoror?
Please consider supporting developers behind the project :)

Donate on OpenCollective Become a Sponsor on GitHub

Configuration

There are two types of configuration:

Core configuration: credentials, timeouts, cache, ...
UI configuration: tiles and layout definition.

Core configuration

Core configuration is set with environment variables. Alternatively, .env file can also be used beside of monitoror binary.

MO_PORT number: Application port
Default: 8080
MO_ADDRESS string: Application address
Can be used to listen a particular network interface instead of all.
Default: 0.0.0.0
MO_CONFIG string: Default configuration URL or path
Can be a path to file on the filesystem where Monitoror Core is running, or an URL. Should point to a valid JSON UI Configuration file.
Note: This config will be used if no config param is set on UI.
MO_CONFIG_{configName} string: You can provide several named configuration, allowing us to only point to the configName on UI side. This make config path and/or URLs server-side only, and keep them private.
Note: MO_CONFIG is an alias for MO_CONFIG_DEFAULT

Most of tile type have specific Core configuration which are documented in the Monitorable tiles section.

See Advanced options section to see more about advanced Core configuration.


# Changing port to 8888
MO_PORT=8888

# UI named configurations
MO_CONFIG="./config.json"
MO_CONFIG_SCREEN1="https://example.com/monitoror-screen1.json"
MO_CONFIG_PRODUCTION="/etc/monitoror/production.json"

UI configuration

UI configuration must be stored in .json file.

There is two way to load the configuration file:

By URL:
http://localhost:8080?config=https://example.com/config.json
By name:
http://localhost:8080?config=screen1
See Core configuration to know how to define named configurations.

Query string parameters

config string

URL to a .json file accessible via HTTP(S), or a config name

theme string

One of the following supported themes:

default — Default theme demo
dark — Dark theme demo

UI configuration file sample

The file is structured like this:


{
  "version": "2.0",
  "columns": 2,
  "tiles": [
    {
      "type": "PING",
      "label": "Localhost",
      "params": { "hostname": "127.0.0.1" }
    },
    {
      "type": "PORT",
      "label": "Dev server",
      "params": { "hostname": "127.0.0.1", "port": 8080 }
    }
  ]
}

UI root properties

version string required: The configuration format version.

Note Current version is "2.0"
columns number required: Number of columns the grid is based on.
zoom number: Zoom factor applied to all tiles.
Default: 1
tiles Tile[] required: List of tile definitions. See below to know more about that.

Tile common properties

Each tile definition has common properties:

type string required

Tile type, must be one of those available in the Monitorable tiles section.

label string

Allow override the automatic Core fill (example: for PING, it's the hostname)

columnSpan number

Number of columns to use.
Must not be greater than number of columns defined in root.
Default: 1

Example On a 4 columns grid, you can extend a tile full width with columnSpan: 4

TIP Fill all previous cells with EMPTY tiles if needed.

rowSpan number

Number of rows to use.
Default: 1

Example Tile can take two rows with rowSpan: 2

configVariant string

Some tiles can have different core configuration.
See Configuration Variants.

Monitorable tiles

Azure DevOps

Show the status of builds and releases.

Core configuration

MO_MONITORABLE_AZUREDEVOPS_URL number required: Azure DevOps base URL
MO_MONITORABLE_AZUREDEVOPS_TOKEN number required: Your private API token
MO_MONITORABLE_AZUREDEVOPS_TIMEOUT number: Timeout in milliseconds before returning error
Default: 1000

Configuration Variants are available for Azure DevOps


MO_MONITORABLE_AZUREDEVOPS_URL="https://azure.example.com/"
MO_MONITORABLE_AZUREDEVOPS_TOKEN="thisisyourtoken"
MO_MONITORABLE_AZUREDEVOPS_TIMEOUT=1000

AZUREDEVOPS-BUILD

Show the status of a build using its definition. In the case of a multi-branch definition, a filter can be specified.

UI configuration

project string required: Azure DevOps project name
definition number required: Pipeline definition ID (from URL definitionId query parameter)
branch string: Branch name
Default: show the last build


{
  "type": "AZUREDEVOPS-BUILD",
  "params": {
    "project": "project",
    "definition": 1,
    "branch": "master"
  }
}

Build name

0:42

5 minutes ago

John Doe

Running Warning Error

AZUREDEVOPS-RELEASE

Show the status of a release using its definition.

UI configuration

project string required: Azure DevOps project name
definition number required: Release definition ID (from URL definitionId query parameter)


{
  "type": "AZUREDEVOPS-RELEASE",
  "params": {
    "project": "project",
    "definition": 1
  }
}

Release name

0:42

5 minutes ago

John Doe

Running Warning Error

GitHub

Show branch or pull request checks status and display search result counters.

Core configuration

MO_MONITORABLE_GITHUB_URL string: GitHub API base URL
Default: https://api.github.com/
MO_MONITORABLE_GITHUB_TOKEN string required: Personal access token
Create a personal access token for Monitoror
MO_MONITORABLE_GITHUB_TIMEOUT number: Timeout in milliseconds before returning error
Default: 5000
MO_MONITORABLE_GITHUB_COUNTCACHEEXPIRATION number: Count cache duration in milliseconds.
GITHUB-COUNT tile use a specific GitHub API with a reduced rate-limit.

Tip If you encounter issues with numerous GITHUB-COUNT tiles, please consider increase this value, and/or use multiple tokens across multiple Configuration Variants.
Default: 30000

Configuration Variants are available for GitHub


MO_MONITORABLE_GITHUB_URL="https://api.github.com/"
MO_MONITORABLE_GITHUB_TOKEN="thisisyourtoken"
MO_MONITORABLE_GITHUB_TIMEOUT=5000
MO_MONITORABLE_GITHUB_COUNTCACHEEXPIRATION=30000

GITHUB-COUNT

Show a counter of issues and pull requests matching a GitHub query.

UI configuration

query string required: Your custom GitHub search query.
See the GitHub documentation to build your own query .

Note This tile only works for issues and pull requests.


{
  "type": "GITHUB-COUNT",
  "label": "Monitoror open issues",
  "params": {
    "query": "is:issue is:open repo:monitoror/monitoror"
  }
}

Monitoror open issues

Success

GITHUB-CHECKS

Show the status of all checks for a given git reference.

UI configuration

owner string required: GitHub group or user (from URL)
repository string required: GitHub repository name (from URL)
ref string required: A git reference, commonly a branch name


{
  "type": "GITHUB-CHECKS",
  "params": {
    "owner": "monitoror",
    "repository": "monitoror",
    "ref": "develop"
  }
}

monitoror @ develop

0:42

5 minutes ago

John Doe

Running Warning Error

GITHUB-PULLREQUEST

Show the status of all checks for a given pull request.

UI configuration

owner string required: GitHub group or user (from URL)
repository string required: GitHub repository name (from URL)
id number required: GitHub pull request ID


{
  "type": "GITHUB-PULLREQUEST",
  "params": {
    "owner": "monitoror",
    "repository": "monitoror",
    "id": 10
  }
}

PR#10 @ monitoror

0:42

5 minutes ago

John Doe

Running Warning Error

GENERATE:GITHUB-PULLREQUEST

Show each open pull request status.

Note This tile is a generator tile that will be replaced by N classic GITHUB-PULLREQUEST tiles.
N being the number of open pull requests.

UI configuration

owner string required: GitHub group or user (from URL)
repository string required: GitHub repository name (from URL)


{
  "type": "GENERATE:GITHUB-PULLREQUEST",
  "params": {
    "owner": "monitoror",
    "repository": "monitoror"
  }
}

GitLab

Show branch or merge request pipeline status and display search issues counters.

Core configuration

MO_MONITORABLE_GITLAB_URL string: GitLab API base URL
Default: https://gitlab.com/
MO_MONITORABLE_GITLAB_TOKEN string required: Personal access token
Create a personal access token for Monitoror
MO_MONITORABLE_GITLAB_TIMEOUT number: Timeout in milliseconds before returning error
Default: 5000

Configuration Variants are available for GitLab


MO_MONITORABLE_GITLAB_URL="https://gitlab.com/"
MO_MONITORABLE_GITLAB_TOKEN="thisisyourtoken"
MO_MONITORABLE_GITLAB_TIMEOUT=5000

GITLAB-COUNT-ISSUES

Show a counter of issues.

UI configuration

projectId number: GitLab project ID (from project settings page)
state string: GitLab issue state
labels string[]: GitLab issue labels
milestone string: GitLab issue milestone
scope string: GitLab issue scope
search string: Space-separated keywords to search in the title or description
authorId number: GitLab user ID (from user settings page)
assigneeId number: GitLab user ID (from user settings page)


{
  "type": "GITLAB-COUNT-ISSUES",
  "label": "Monitoror open issues",
  "params": {
    "projectId": 42,
    "state": "opened"
  }
}

Monitoror open issues

Success

GITLAB-PIPELINE

Show the status of a pipeline for a given git reference.

UI configuration

projectId number required: GitLab project ID (from project settings page)
ref string required: A git reference, commonly a branch name


{
  "type": "GITLAB-PIPELINE",
  "params": {
    "projectId": 42,
    "ref": "develop"
  }
}

monitoror @ develop

0:42

5 minutes ago

John Doe

Running Warning Error

GITLAB-MERGEREQUEST

Show the status of a pipeline for a given merge request.

UI configuration

projectId number required: GitLab project ID (from project settings page)
id number required: GitLab merge request ID


{
  "type": "GITLAB-MERGEREQUEST",
  "params": {
    "projectId": 42,
    "id": 10
  }
}

MR#10 @ monitoror

0:42

5 minutes ago

John Doe

Running Warning Error

GENERATE:GITLAB-MERGEREQUEST

Show each open merge request status.

Note This tile is a generator tile that will be replaced by N classic GITLAB-MERGEREQUEST tiles.
N being the number of open merge requests.

UI configuration

projectId number required: GitLab project ID (from project settings page)


{
  "type": "GENERATE:GITLAB-MERGEREQUEST",
  "params": {
    "projectId": 42
  }
}

HTTP

Send a GET request to a URL, then check the status code and the content.

Core configuration

MO_MONITORABLE_HTTP_TIMEOUT number: Timeout in milliseconds before returning error
Default: 1000
MO_MONITORABLE_HTTP_SSLVERIFY boolean: Check if SSL certificate is valid
Default: true

Configuration Variants are available for HTTP


MO_MONITORABLE_HTTP_TIMEOUT=1000
MO_MONITORABLE_HTTP_SSLVERIFY=true

HTTP-STATUS

Will only check that status code is in range.

UI configuration

url string required: URL to fetch over HTTP(S)
statusCodeMin number: Minimum HTTP status code
Default: 200
statusCodeMax number: Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-STATUS",
  "params": {
    "url": "http://localhost/test",
    "statusCodeMax": 299
  }
}

http://localhost/test

Success Error

HTTP-RAW

Performed checks:

status code in range
content matches the regex correctly

UI configuration

url string required: URL to fetch over HTTP(S)
statusCodeMin number: Minimum HTTP status code
Default: 200
statusCodeMax number: Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399
regex string: Match or first group will be show in tile.
Regex format is RE2, described at https://golang.org/s/re2syntax
Note: Regex must be JSON-escaped
Default: .*

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-RAW",
  "params": {
    "url": "http://localhost/tag",
    "regex": "version:\\s*([^\\s]*)"
  }
}

http://localhost/tag

v2020.1.42

Success Error

HTTP-FORMATTED

Performed checks:

status code in range
content can be parsed as JSON, XML or YAML (see format)
presence of the key
the key value matches the regex correctly

UI configuration

url string required

URL to fetch over HTTP(S)

format string required

Must be one of following:

JSON
XML
YAML

key string required

Path to the key from which the value is get, following a jq-like format

statusCodeMin number

Minimum HTTP status code
Default: 200

statusCodeMax number

Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399

regex string

Match or first group will be show in tile.
Regex format is RE2, described at https://golang.org/s/re2syntax
Note: Regex must be JSON-escaped
Default: .*

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-FORMATTED",
  "params": {
    "url": "http://localhost/count",
    "format": "JSON",
    "key": "sub.\"dotted.key\".[0]"
  }
}

http://localhost/count

1337

Success Error

Jenkins

Jenkins tiles are used to display the status of a build.

Core configuration

MO_MONITORABLE_JENKINS_URL string required: Jenkins base URL
MO_MONITORABLE_JENKINS_LOGIN string required: Your login
MO_MONITORABLE_JENKINS_TOKEN string required: Your private API token
MO_MONITORABLE_JENKINS_TIMEOUT number: Timeout in milliseconds before returning error
Default: 2000
MO_MONITORABLE_JENKINS_SSLVERIFY boolean: Check if SSL certificate is valid
Default: true

Configuration Variants are available for Jenkins


MO_MONITORABLE_JENKINS_URL="https://jenkins.example.com"
MO_MONITORABLE_JENKINS_LOGIN="username"
MO_MONITORABLE_JENKINS_TOKEN="thisisyourtoken"
MO_MONITORABLE_JENKINS_TIMEOUT=2000
MO_MONITORABLE_JENKINS_SSLVERIFY=true

JENKINS-BUILD

Show the status of a build, pipeline or specific branch of a multi-branch job or pipeline.

UI configuration

job string required: Jenkins job ID
branch string required if multi-branch: Branch name


{
  "type": "JENKINS-BUILD",
  "params": {
    "job": "test-job",
    "branch": "master"
  }
}

Test job

0:42

5 minutes ago

John Doe

Running Warning Error

GENERATE:JENKINS-BUILD

Show the status of all branches of a multi-branch pipeline.

Note This tile is a generator tile that will be replaced by N classic JENKINS-BUILD tiles.
N being the number of checks that match the filters that have been set.

UI configuration

job string required: Jenkins job ID
match string: Filter branch names with a regex (whitelist)
unmatch string: Inverted regex filter based on branch names (blacklist)

Note match and unmatch options cannot be used at the same time.

Note Regex format is RE2, described at https://golang.org/s/re2syntax, and must be JSON-escaped


{
  "type": "GENERATE:JENKINS-BUILD",
  "params": {
    "job": "test-job",
    "match": "^feat/"
  }
}

Ping

Get ping status and duration from a hostname.

Core configuration

MO_MONITORABLE_PING_COUNT number: Number of ping sent, used to retrieve an average value
Default: 2
MO_MONITORABLE_PING_INTERVAL number: Interval between ping in milliseconds
Default: 100
MO_MONITORABLE_PING_TIMEOUT number: Global time in milliseconds before returning error
Default: 1000

Configuration Variants are available for Ping


MO_MONITORABLE_PING_COUNT=2
MO_MONITORABLE_PING_INTERVAL=100
MO_MONITORABLE_PING_TIMEOUT=1000

Note for Linux and macOS users
If you see PING: disabled at Monitoror launch, you need to relaunch Monitoror as super-user to get PING tiles working.

On Linux, a cleaner solution is to run setcap as super-user to allow Monitoror to bind to raw sockets: setcap cap_net_raw=+ep monitoror

PING

Show ping to a hostname status and duration.

UI configuration

hostname string required: Hostname to ping


{
  "type": "PING",
  "params": {
    "hostname": "localhost"
  }
}

localhost

42ms

Success Error

Pingdom

Pingdom checks interface with pingdom.com/website-monitoring

Core configuration

MO_MONITORABLE_PINGDOM_URL string: Pingdom API base URL
Default: https://api.pingdom.com/api/3.1
MO_MONITORABLE_PINGDOM_TOKEN number required: Your private API token
On Pingdom, go to Integrations > The Pingdom API, then click Add API token
MO_MONITORABLE_PINGDOM_TIMEOUT number: Timeout in milliseconds before returning error
Default: 1000
MO_MONITORABLE_PINGDOM_CACHEEXPIRATION number: Specific cache duration for Pingdom check
Default: 30000

Configuration Variants are available for Pingdom


MO_MONITORABLE_PINGDOM_URL="https://api.pingdom.com/api/3.1"
MO_MONITORABLE_PINGDOM_TOKEN="thisisyourtoken"
MO_MONITORABLE_PINGDOM_TIMEOUT=1000
MO_MONITORABLE_PINGDOM_CACHEEXPIRATION=30000

PINGDOM-CHECK

Show state of a Pingdom specific check.

UI configuration

id number required: Pingdom check ID


{
  "type": "PINGDOM-CHECK",
  "params": {
    "id": 10
  }
}

Check name

Success Error

PINGDOM-TRANSACTION-CHECK

Show state of a Pingdom specific transaction check.

UI configuration

id number required: Pingdom transaction check ID


{
  "type": "PINGDOM-TRANSACTION-CHECK",
  "params": {
    "id": 10
  }
}

Check name

Success Error

GENERATE:PINGDOM-CHECK

Show state of all Pingdom checks.

Note This tile is a generator tile that will be replaced by N classic PINGDOM-CHECK tiles.
N being the number of checks that match the filters that have been set.

UI configuration

tags string

Pingdom check tag list separated by commas

sortBy string

Allow to sort checks by following:

name


{
  "type": "GENERATE:PINGDOM-CHECK",
  "params": {
    "tags": "eu-west",
    "sortBy": "name"
  }
}

GENERATE:PINGDOM-TRANSACTION-CHECK

Show state of all Pingdom transaction checks.

Note This tile is a generator tile that will be replaced by N classic PINGDOM-TRANSACTION-CHECK tiles.
N being the number of checks that match the filters that have been set.

UI configuration

tags string

Pingdom transaction check tag list separated by commas

sortBy string

Allow to sort transaction checks by following:

name


{
  "type": "GENERATE:PINGDOM-TRANSACTION-CHECK",
  "params": {
    "tags": "eu-west",
    "sortBy": "name"
  }
}

Port

Check if a port is open with something listening behind.

Core configuration

MO_MONITORABLE_PORT_TIMEOUT number: Timeout in milliseconds before returning error
Default: 1000

Configuration Variants are available for Port


MO_MONITORABLE_PORT_TIMEOUT=1000

PORT

Will success when the port is open with something listening behind.

UI configuration

hostname string required: Hostname to scan
port number required: Port to scan


{
  "type": "PORT",
  "params": {
    "hostname": "localhost",
    "port": 443
  }
}

localhost:443

Success Error

Travis CI

Show Travis CI build status and progress.

Core configuration

MO_MONITORABLE_TRAVISCI_URL string: Travis CI API base URL
Default: https://api.travis-ci.com/
MO_MONITORABLE_TRAVISCI_TOKEN string required: Your private API token
MO_MONITORABLE_TRAVISCI_TIMEOUT number: Timeout in milliseconds before returning error
Default: 2000

Configuration Variants are available for Travis CI


MO_MONITORABLE_TRAVISCI_URL="https://api.travis-ci.com/"
MO_MONITORABLE_TRAVISCI_TOKEN="thisisyourtoken"
MO_MONITORABLE_TRAVISCI_TIMEOUT=2000

TRAVISCI-BUILD

Show the status of the build of the branch of a specific project.

UI configuration

owner string required: GitHub group or user (from URL)
repository string required: GitHub repository name (from URL)
branch string: Branch name
Default: show the last build


{
  "type": "TRAVISCI-BUILD",
  "params": {
    "owner": "Alex-D",
    "repository": "check-disk-space",
    "branch": "master"
  }
}

Build name

0:42

5 minutes ago

John Doe

Running Warning Error

In this example, the tile will show the status of github.com/Alex-D/check-disk-space@master

Utility tiles

Empty

Add an empty tile (to fill lines, columns, align things, ...).


{ "type": "EMPTY" }

Group

Group sub tiles in one tile to get the global status of all sub tiles.

Note Group will only show non-successful tiles. If the tile is empty: everything is fine!

UI configuration

tiles Tile[] required: List of tile definitions

Note Cannot contain GROUP nor EMPTY tiles


{
  "type": "GROUP",
  "label": "Group name",
  "tiles": [
    {
      "type": "PING",
      "label": "Test",
      "params": {
        "hostname": "example.com"
      }
    },
    {
      "type": "AZUREDEVOPS-BUILD",
      "params": {
        "project": "project",
        "definition": 1,
        "branch": "master"
      }
    },
    {
      "type": "PINGDOM-CHECK",
      "params": {
        "id": 42
      }
    }
  ]
}

Group name

Test

master

0:42

Check name

3 / 3

1 / 3

Running Error Success

Advanced options

Configuration Variants

Configuration Variants allow you to monitor multiple servers (e.g.: multiple Jenkins servers).

To do so, you will need some more lines in your core configuration and some additional configVariant field in UI configuration.


# In your .env file
MO_MONITORABLE_JENKINS_URL="http://jenkins.example.com"
MO_MONITORABLE_JENKINS_LOGIN="username"
MO_MONITORABLE_JENKINS_TOKEN="thisisyourtoken"

MO_MONITORABLE_JENKINS_PROD_URL="http://jenkins-prod.example.com"
MO_MONITORABLE_JENKINS_PROD_LOGIN="username"
MO_MONITORABLE_JENKINS_PROD_TOKEN="thisisyourtoken"


{
  "columns": 2,
  "tiles": [
    {
      "type": "JENKINS-BUILD",
      "params": { "job": "build", "branch": "master" }
    },
    {
      "type": "JENKINS-BUILD",
      "params": { "job": "deploy-internal" }
    },
    {
      "type": "JENKINS-BUILD",
      "configVariant": "prod",
      "params": { "job": "deploy-prod" }
    },
  ]
}

In this example:

the first 2 builds will fetch their data from http://jenkins.example.com
the last one from http://jenkins-prod.example.com

Core cache

MO_UPSTREAMCACHEEXPIRATION number: Throttle delay in milliseconds for external requests. Avoid overloading services
Default: 10000
MO_DOWNSTREAMCACHEEXPIRATION number: Duration in milliseconds of the previous result by URL which is returned in case of timeout. Avoid false negative on CI checks
Default: 120000
MO_INITIALMAXDELAY number: Duration in milliseconds used as the maximum delay on each tile's first update to avoid bursting N requests at the same time on start
Default: 1700