Skip to content

Events & Event handlers

Jump to bottom
adamkobor edited this page Sep 29, 2020 · 12 revisions

Kuvasz is built around events and their handlers. Every check that Kuvasz makes, emits an event, and the handlers who are subscribed to them handle these events in different ways.

Uptime check events

Uptime checks are happening with the interval you set for a given monitor. Kuvasz follows redirects if there is a valid Location header in the response.

MonitorUpEvent

Has been emitted when a website passes the uptime check, i.e. it's live and "healthy". It also contains the latency of the response.

MonitorDownEvent

Has been emitted when a website is unreachable, and it contains the cause of the error.

RedirectEvent

Kuvasz is following redirects through HTTP calls, so when a call is forwarded to an other address, a RedirectEvent will be emitted. It contains the new location from the Location header of the original response.

SSL check events

SSL checks are happening on a daily basis, exactly 24 hours later than they have been scheduled for the first time.

SSLValidEvent

Has been emitted when everything's fine with your certificate (valid and won't expire in 30 days).

SSLInvalidEvent

Has been emitted when there is a problem with your site's certificate, so it's considered invalid.

SSLWillExpireEvent

Has been emitted when your certificate will expire in 30 days.

Event handlers

Event handlers are also known as "integrations".

You can get information about the configured handlers through the built-in /info endpoint, which can be called without authentication as well. The response will be an object like that:

{
  "handlers": {
    "log-event-handler.enabled": true,
    "smtp-event-handler.enabled": false,
    "slack-event-handler.enabled": true,
    "telegram-event-handler.enabled": true,
    "pagerduty-event-handler.enabled": false
  }
}

STDOUT (log-event-handler)

Handled events:

  • MonitorUpEvent
  • MonitorDownEvent
  • RedirectEvent
  • SSLValidEvent
  • SSLInvalidEvent
  • SSLWillExpireEvent

This handler writes a simple log message to STDOUT and can be switched off through the ENABLE_LOG_EVENT_HANDLER environment variable.

Examples:

  • ✅ Your monitor "test_up" (https://test.com) is UP (200). Latency was: 1826ms.
  • 🚨 Your monitor "test_down" (https://test2.com) is DOWN. Reason: Connect Error: Connection refused: test2.com
  • ℹ Request to "test_redirected" (https://redirected.com) has been redirected
  • 🔒️ Your site "test_good_ssl" (https://good-ssl.com) has a VALID certificate
  • 🚨 Your site "test_bad_ssl" (https://no-subject.badssl.com/) has an INVALID certificate. Reason: PKIX path validation failed

SMTP (smtp-event-handler)

Handled events:

  • MonitorUpEvent
  • MonitorDownEvent
  • SSLValidEvent
  • SSLInvalidEvent
  • SSLWillExpireEvent

This handler sends email messages about the state of your monitors, and can be set up through environment variables. Same events would be suppressed, which means that two or more consecutive UP or DOWN events wouldn't result in more than one email notification.

Slack (slack-event-handler)

Handled events:

  • MonitorUpEvent
  • MonitorDownEvent
  • SSLValidEvent
  • SSLInvalidEvent
  • SSLWillExpireEvent

This handler sends notifications through an incoming webhook to Slack about the state of your monitors, and can be set up through environment variables. Same events would be suppressed, which means that two or more consecutive UP or DOWN events wouldn't result in more than one notification. If you aren't familiar with Slack's webhooks, you can read about the initial setup here.

Telegram (telegram-event-handler)

Handled events:

  • MonitorUpEvent
  • MonitorDownEvent
  • SSLValidEvent
  • SSLInvalidEvent
  • SSLWillExpireEvent

This handler sends notifications through the Bot API to Telegram about the state of your monitors, and can be set up through environment variables. Same events would be suppressed, which means that two or more consecutive UP or DOWN events wouldn't result in more than one notification. If you aren't familiar with Telegram's bots, you can read about them here.

PagerDuty (pagerduty-event-handler)

Handled events:

  • MonitorUpEvent
  • MonitorDownEvent
  • SSLValidEvent
  • SSLInvalidEvent
  • SSLWillExpireEvent

This handler triggers alerts and is also able to resolve them automatically on PagerDuty, based on the events above. To make it work, you have to enable the handler through an environment variable, any you also have to provide your PagerDuty service's integration key for the monitor you want to integrate with. You can find more information about the setup process here: Integrating with PagerDuty.

Clone this wiki locally