Skip to content

ICMP monitors

Before you start...

Make sure that you carefully read the common documentation about managing the monitors!

Management methods

If you navigate to the Web UI of Kuvasz, you can create a new monitor on the Dashboard, or on the Ping (ICMP) monitors page, by clicking the "+ New Monitor" button in the page header.

YAML monitor reference
icmp-monitors:
- name: "My ICMP Monitor" # (1)!
  display-name: "Shown name" # (13)!
  category: "Core services" # (11)!
  host: "example.com" # (2)!
  uptime-check-interval: 60 # (3)!
  packet-count: 3 # (4)!
  timeout-seconds: 5 # (5)!
  packet-loss-threshold: 100 # (6)!
  failure-count-threshold: 1 # (7)!
  ignore-connectivity-check: false # (12)!
  enabled: true # (8)!
  metrics-history-enabled: true # (9)!
  integrations: # (10)!
    - "slack:devops_channel"
# ... other monitors
  1. Name: The name of the monitor, which must be unique across all ICMP monitors.
  2. Host: The hostname or IP address to ping.
  3. Uptime check interval: The interval in seconds at which the uptime checks will be performed. The minimum value is 5 seconds.
  4. Packet count: The number of ICMP packets to send per check. Must be between 1 and 10. Defaults to 3.
  5. Timeout seconds: The per-ping timeout in seconds. Must be between 1 and 30. Defaults to 5.
  6. Packet loss threshold: The packet loss percentage (1-100) at or above which the check is considered DOWN. The default value of 100 means all packets must fail to trigger a DOWN event.
  7. Failure count threshold: The number of consecutive failures that should occur before the monitor is considered down. Defaults to 1.
  8. Enabled: Whether the monitor is enabled or not. If it's disabled, it won't be checked, and no events will be recorded for it.
  9. Metrics history enabled: Whether metrics history (latency, packet loss) is recorded for the monitor. Defaults to true.
  10. Integrations: A list of integrations to assign to the monitor. The format is "{integration-type}:{integration-name}", where integration-type is the type of the integration (e.g. email, slack, etc.), and integration-name is the name of the integration as defined in the integrations section of your YAML file. Example: email:my-email-integration.
  11. Category: An optional, free-form category to group the monitor on the status pages (e.g. a product or service name).
  12. Ignore connectivity check: Whether the monitor should keep being checked even while Kuvasz considers its own outbound connectivity lost. Defaults to false.
  13. Display name: An optional name that is shown instead of the name, e.g. on the status pages and in the notifications. It doesn't have to be unique, and you can change it without losing the history of the monitor.

This section won't go into details about the API or about exact API calls, since it's well documented and must be self-explanatory. You can find more information about the available endpoints and their usage in the API documentation.

However, here are few of the most important endpoints:

  • GET /api/v2/icmp-monitors - List all ICMP monitors
  • GET /api/v2/icmp-monitors/{id} - Get a specific ICMP monitor by its ID
  • POST /api/v2/icmp-monitors - Create a new ICMP monitor
  • PATCH /api/v2/icmp-monitors/{id} - Update an existing ICMP monitor
  • DELETE /api/v2/icmp-monitors/{id} - Delete an ICMP monitor

Settings

Name

3.10.0 string name

The name of the monitor, which must be unique across all ICMP monitors.

Renaming a monitor in the YAML file

If you manage your monitors in the YAML file, Kuvasz recognizes a monitor by its name when it starts. So a monitor with a new name is a new monitor: the one with the old name is deleted, together with its whole history (events, incidents, latency data). If you only want to change how the monitor is shown, use the display name instead.

Display name

4.8.0 string display-name

An optional name that is shown instead of the name wherever people see the monitor: on the Web UI, on the status pages and in the notifications. Unlike the name, it doesn't have to be unique, and you can change it at any time without losing anything. The default is null, which means that the name is shown.

This is the way to rename a monitor that you manage in the YAML file: change its display name and keep its name, so the monitor keeps its history. The Web UI still shows the name next to the display name, because the YAML file, the status pages and the maintenance windows refer to the monitor by its name.

Category

4.4.0 string category

An optional, free-form category (up to 100 characters), e.g. the name of a product or a service, that is used to group the monitor on the status pages. Monitors that share the same category are displayed together in a dedicated section there, with an aggregated status per category. The default is null, which means that the monitor is not categorized.

A category is more than a label: a status page and a maintenance window can select their monitors by it, so tagging a monitor is enough to put it on the right page and into the right maintenance window.

On the Web UI the field offers the categories that are already in use, so you can pick an existing one instead of re-typing it. Typing a category that doesn't exist yet creates it right there.

Host

3.10.0 string host

The hostname or IP address to ping. Can be a domain name (e.g. example.com) or an IPv4/IPv6 address.

Uptime check interval

3.10.0 number uptime-check-interval

The interval in seconds at which the uptime checks will be performed. The minimum value is 5 seconds.

Enabled

3.10.0 true boolean enabled

Whether the monitor is enabled or not. If it's disabled, it won't be checked, and no events will be recorded for it.

Packet count

3.10.0 3 number packet-count

The number of ICMP packets to send per check. Must be between 1 and 10. A higher value gives a more accurate picture of connectivity, but each check will take longer.

Timeout seconds

3.10.0 5 number timeout-seconds

The per-ping timeout in seconds. Must be between 1 and 30. If an individual ICMP packet does not receive a reply within this time it is considered lost.

Packet loss threshold

3.10.0 100 number packet-loss-threshold

The packet loss percentage (1-100) at or above which the check is considered DOWN. The default value of 100 means that all packets must be lost for the monitor to be marked as DOWN. Lower values make the check more sensitive - for example, a value of 50 will trigger a DOWN event if half of the sent packets are lost.

Failure count threshold

3.10.0 1 number failure-count-threshold

The number of consecutive failures that should occur before the monitor is considered down. Defaults to 1, which means that the monitor will be considered down after the first failure. If you set it to a higher value, for example 3, the monitor will be considered down only after 3 consecutive failures, which can help to reduce false positives in case of temporary network issues or other transient problems.

Metrics history enabled

3.10.0 true boolean metrics-history-enabled

Whether the metrics history (latency and packet loss over time) is enabled or not. If it's disabled, the monitor won't record the measured metrics. If you disable it on a monitor that has already recorded metrics history, the existing history will be deleted.

Integrations

3.10.0 empty list integrations

A list of integrations to assign to the monitor.

If you're using YAML, or the API, the format is "{type}:{name}", where type is the alias of the integration (e.g. email, slack, etc.), and name is the name of the integration as defined in the integrations section of your YAML file. Example: email:my-email-integration.

Tip

You can add/keep disabled integrations in the list, but they will not be used for the monitor. This is useful if you want to enable them later without modifying the monitor's configuration.

Global integrations can be explicitly added too, which is handy if you're about to make them non-global later, but you want to make sure that they will be assigned to certain monitors even after the change.

Ignore connectivity check

4.5.0 false boolean ignore-connectivity-check

Whether the monitor should be checked even while the connectivity check considers Kuvasz to be disconnected. Defaults to false, which means the monitor is suspended together with all the others during an outage.

Enable it for monitors that don't depend on the outbound connectivity of Kuvasz at all — a service on the same LAN, in the same cluster, or on the very same host. Those keep working during an internet outage, so suspending them would only hide a real failure from you.

Info

This flag has no effect at all when the connectivity check is disabled, which is the default. You can set it freely regardless, so it's already in place if you decide to turn the feature on later.

Common operations

Toggling a monitor

You can enable or disable a monitor at any time, which is useful if you want to temporarily stop monitoring a specific host without deleting it.

Disabled monitors won't be counted in the cumulated metrics, like uptime ratio.

Look for the toggle switches with the sign.

Set the enabled field to true or false in your YAML file.

icmp-monitors:
- name: "My ICMP Monitor"
  host: "example.com"
  enabled: false

Use the PATCH /api/v2/icmp-monitors/{id} endpoint to update the enabled field of the monitor.

Deleting a monitor

If you delete a monitor, it will be removed from the database, and all of its recorded events and metrics (i.e. metrics history, uptime checks, etc.) will be deleted as well. This is a destructive operation, so make sure you really want to delete the monitor.

Look for the delete button with the sign next to the monitor you want to delete.

Remove the monitor from your YAML file, and then restart Kuvasz to apply the changes.

Use the DELETE /api/v2/icmp-monitors/{id} endpoint to delete the monitor by its ID.

Modifying the assigned integrations

You can modify the assigned integrations of a monitor by clicking on the configure button with the sign on the monitor's detail page (look for the Integrations block), where you can add or remove integrations as needed.

Modify the integrations property of your affected monitor, by adding or removing list items, and then restart Kuvasz to apply the changes.

icmp-monitors:
- name: "My ICMP Monitor"
  host: "example.com"
  uptime-check-interval: 60
  integrations:
    - "slack:devops_channel"
    - "email:my-email-integration"

Use the PATCH /api/v2/icmp-monitors/{id} endpoint to update the integrations field of the monitor. You can add or remove integrations as needed.

{
  "integrations": [
    "email:my-email-integration",
    "slack:my-slack-integration"
  ]
}