Managing monitors
There are three ways to manage your monitors in Kuvasz: through the Web UI, using a YAML configuration file, or via the REST API. Each method has its own advantages, and you can choose the one that best fits your workflow.
Key concepts for all methods
- The name of the monitor must be unique per monitor type, otherwise the creation/update will fail. If you want to update an existing monitor, you can use the same name, of course.
- The UI and the API will be in read-only mode if you have defined your monitors via YAML
Management methods - good to know
The Web UI should be intuitive and user-friendly enough to make it straightforward to create, edit, and manage your monitors. You can access the UI by navigating to the root of your Kuvasz instance (e.g. http://0.0.0.0:8080 if you're running it with the default port setup).
Consequences of describing your monitors as YAML
Be aware that if you define your monitors via YAML, you cannot use the UI, or the API to modify them, you can only view them there (read-only operations are permitted)!
In this case Kuvasz reads your YAML file on startup, compares the monitors in there with the existing ones in the database, and uses the YAML file as the source of truth.
The same applies if you used the UI or the API before to manage your monitors, and you decide to switch to YAML: unless your YAML definition matches the existing monitors by their name, existing monitors could be deleted or modified.
Restoring from a YAML backup
You can export your monitors from the UI under Settings → Backup & Restore → Export monitors (YAML), or via GET /api/v2/monitors/export/yaml. To restore that backup later, use Settings → Backup & Restore → Import monitors (YAML) or the POST /api/v2/monitors/import/yaml API endpoint.
Restoring a backup is destructive
The import reconciles per monitor type that is present in the backup with at least one entry:
- For each monitor type that has at least one entry in the backup, monitors with the same name will be updated with the values from the backup, monitors that exist in the database but are not in the backup will be deleted, and monitors in the backup that do not exist will be created.
- Monitor types that are missing from the backup entirely (no key, or no entries) are left untouched. To delete every monitor of a given type, use the YAML bootstrap config with an explicit empty array (
http-monitors: []) for that type instead. - The import does not switch the monitors to read-only mode; you can keep managing them through the UI and API afterwards.
- Monitor types currently managed via YAML (read-only mode) are silently skipped during the import. The remaining writable types are still imported as usual.
- Referenced integrations that are not configured are skipped (with a warning) instead of failing the import, so the monitor is still imported without the missing integration. Configure your integrations before restoring your monitors to keep every reference intact.
Before importing, you can enable Simulate only (dry run) in the UI or pass dryRun=true to the API. This runs the import without persisting anything and reports exactly which monitors would be imported, which would be deleted, and which referenced integrations would be skipped, so you can review everything before committing to the import.
What happens if you add one or more monitor to your YAML file?
- If there is a monitor in the database that is not in the YAML file, it will be deleted.
- If there is a monitor in the YAML file that is not in the database, it will be created and added to the database.
- If there is a monitor in both the YAML file and the database, and they have the same name, the monitor in the database will be updated with the values from the YAML file.
What happens if you provide an empty array for a monitor type in the YAML file?
http-monitors: []
# or
push-monitors: []
# or
icmp-monitors: []
# or
tcp-monitors: []
# or
dns-monitors: []
In this case all monitors of that type in the database will be deleted.
What happens if you remove the relevant properties from the YAML file?
By that we mean that your YAML file doesn't contain the relevant property keys (i.e. push-monitors, http-monitors, icmp-monitors, tcp-monitors, dns-monitors, etc.), or they are not explicitly set to an empty array (see the example below).
# Watch out for the missing property values here.
# This is considered as a missing configuration,
# entries in the database will not be touched,
# external write to the monitors are allowed.
http-monitors:
# or
push-monitors:
# or
icmp-monitors:
# or
dns-monitors:
In this case all monitors in the database will be kept (i.e. the ones that were created before via YAML). This is especially useful if you want to restore your monitors from your exported YAML backup, but you want to manage them on the UI in the future.
Changing a monitor's name
If you change the name of an existing monitor in the YAML file, it will be treated as a new monitor, and the old one will be deleted. This also means that all of your previously recorded events and metrics (i.e. latency history, uptime checks, etc.) will be lost for that monitor.
It might be beneficial to use the REST API of Kuvasz if you would like to build a low-level integration.
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.
Available monitor types
-
HTTP & SSL monitors
With flexible configuration, adjustable intervals, headers, keyword matching, expected response status codes, response time checks and more.
-
Push (a.k.a. "cron") monitors
Monitor your services that are not accessible via HTTP, for example backups, cron jobs, etc.
-
Ping (ICMP) monitors
Check the reachability and latency of any host by sending ICMP echo requests (pings) to it.
-
TCP monitors
Check whether any TCP service accepts connections, and track connect latency.
-
DNS monitors
Check that a name resolves to the right records, and get notified when the answer changes.