Configuration File

Monika uses a YAML file to define all the settings and configurations. You can find a sample configuration file in the repository called monika.example.yml.

Pro tips: If you use Visual Studio Code (VSCode) on a regular basis, you can write the configuration file with the help of auto completion by installing the YAML extension for VSCode. More information can be found in our Creating Monika Configuration from Scratch using Autocomplete in Visual Studio Code blog post.

Another pro tips: If you'd rather use a GUI to create the configuration file, you can use the Monika Config Generator web app.

In general Monika and its configuration file, monika.yml is divided into three sections. A probe, an alert and a notification section.

Probes

Probes describe one or more requests to perform on your service to test. A probe will include the request, the URL to test, its method, timeout and any headers and body that you might wish to add.

Here is an example probe:

1 probes:
2   - id: 'submission_test'
3     name: HTML form submission
4     description: simulate html form submission
5     interval: 10 # in seconds
6     requests:
7       - url: https://httpbin.org/status/200
8         method: POST
9         timeout: 7000 # in milliseconds
10         headers:
11           Content-Type: application/x-www-form-urlencoded

For further details on probes, check the Probes guide.

Alerts

Alerts describe the conditions to trigger a notification. Alerts are basically test conditions for your service, such as http status, response time, or a particular response body.

The example below defines two alerts that will send notification if the HTTP response status is 500 or if the response time is greater than 150 ms.

1 alerts:
2   - assertion: response.status == 500
3     message: response status is 500
4   - assertion: response.time > 150 # in milliseconds
5     message: response time is slow

For details on alerts and how you can define different kind of queries, see the Alerts guide.

Notifications

Once an alert is triggered, Monika will send one or more notifications through any of the supported channels that you defined.

For instance, a simple desktop notification needs to be defined as follows:

1 notifications:
2   - id: my-desktop-notif
3     type: desktop

Or an e-mail notification via your own SMTP server can be done by defining the following configuration:

1 notifications:
2   - id: random-string-smtp
3     type: smtp
4     data:
5       recipients: [RECIPIENT_EMAIL_ADDRESS]
6       hostname: SMTP_HOSTNAME
7       port: 587
8       username: SMTP_USERNAME
9       password: SMTP_PASSWORD

Note that you can define more than one notification and Monika will notify you through them all when an alert is triggered.

Monika supports a wide variety of communication channels such as WhatsApp, Discord, Google Chat, and many more. For the complete list of the different notification channels that Monika supports, visit the Notifications page.

Pro tips: If the communication app you are using with your team is not supported by Monika, you can follow our guide to add it to Monika in Add your choice of notification channels to Monika blog post. Some of the notification channels that Monika supports are thanks to fellow developers' open source contributions!