Documentation

Quick access

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:

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
5 minutes ago
John Doe

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
5 minutes ago
John Doe

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
18

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
5 minutes ago
John Doe

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
5 minutes ago
John Doe

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
18

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
5 minutes ago
John Doe

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
5 minutes ago
John Doe

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

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

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

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
5 minutes ago
John Doe

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

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

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

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

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
5 minutes ago
John Doe

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
3 / 3
1 / 3

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