diff --git a/widgets/kuvasz-uptime-metrics/README.md b/widgets/kuvasz-uptime-metrics/README.md new file mode 100644 index 0000000..e910e2e --- /dev/null +++ b/widgets/kuvasz-uptime-metrics/README.md @@ -0,0 +1,441 @@ +## Introduction + +These are some nice widgets to display various type of data from a [Kuvasz Uptime](https://kuvasz-uptime.dev) instance, using the custom-api widget type. + +_Kudos to the makers of the Gatus community widgets ([**Nedra1988**](https://github.com/Nedra1998) and [**Jack-Overflow**](https://github.com/Jack-Overflow)), they made a really nice foundation to work with!)_ + +If you experience any issues, just open an issue and tag me (`@adamkobor`)! + +## Preview + +![HTTP full style](preview.png) + +![HTTP compact stlye](http-compact-preview.png) + +![Push](push-preview.png) + +![HTTP stats](http-stats-preview.png) + +## Stats + +This widget can be used for both HTTP and push monitor stats, depending on the configuration option. It shows the total count, the up and down monitors, and the count of the incidents, the affected monitors and the uptime ratio over a given period (also configurable). + +**Options** + +* `base-url`: your Kuvasz host (mandatory), better to set it up via the KUVASZ_HOST environment variable +* `api-key`: your own API key for Kuvasz, optional if you disabled authentication. Better to set it up via the KUVASZ_API_KEY +* `monitor-type`: either "http" or "push" (mandatory) +* `period`: an ISO-8601 interval string for the cumulative stats (incidents, affected monitors, uptime ratio), the default is 24 hours + +**YAML** + +```yaml +- type: custom-api + title: Kuvasz HTTP stats + cache: 5m + options: + base-url: ${KUVASZ_HOST} + api-key: ${KUVASZ_API_KEY} + period: 7d + monitor-type: http + template: | + {{/* Required config options */}} + {{ $baseURL := .Options.StringOr "base-url" "" }} + {{ $monitorType := .Options.StringOr "monitor-type" "" }} + + {{/* Optional config options */}} + {{ $apiKey := .Options.StringOr "api-key" "" }} + {{ $period := .Options.StringOr "period" "24h" }} + + {{ $stats := newRequest (print $baseURL "/api/v2/" $monitorType "-monitors/stats/?period=" $period ) + | withHeader "X-Api-Key" $apiKey + | getResponse }} + {{ $uptimeValue := mul 100 ($stats.JSON.Float "history.uptimeStats.uptimeRatio") }} + +
+
+
+

{{ $stats.JSON.Int "actual.uptimeStats.total" }}

+

TOTAL

+
+
+

{{ $stats.JSON.Int "actual.uptimeStats.up" }}

+

UP

+
+
+

{{ $stats.JSON.Int "actual.uptimeStats.down" }}

+

DOWN

+
+
+
+
+

{{ $stats.JSON.Int "history.uptimeStats.incidents" }}

+

INCIDENTS

+
+
+

{{ $stats.JSON.Int "history.uptimeStats.affectedMonitors" }}

+

AFFECTED

+
+
+

{{ printf "%.2f" $uptimeValue }}%

+

UPTIME

+
+
+
+``` + +## HTTP monitors + +This one lists the HTTP monitors from Kuvasz with their uptime ratio, latency metrics (configurable) and state. You can also set up custom icons, URLs or you can decide which monitors you would like to show. + +**Options** + +* `base-url`: your Kuvasz host (mandatory), better to set it up via the KUVASZ_HOST environment variable +* `api-key`: your own API key for Kuvasz, optional if you disabled authentication. Better to set it up via the KUVASZ_API_KEY environment variable +* `style`: either "full" or "compact". The full version can have custom icons and displays 2 metrics, while the compact variant only shows 1 metric and doesn't support custom icons. Default is "full". +* `period`: an ISO-8601 interval string for the cumulative stats (incidents, affected monitors, uptime ratio), the default is 24 hours +* `show-metrics`: whether to load and display any kind of metrics, or disable them completely. Be aware, that if you would like to show metrics for a lot of monitors, it could slow down your dashboard since the metrics need to be fetched on a per monitor basis. +* `compact-metric`: the metric to show in the compact variant, it's either "uptime" or "latency", default is "uptime. +* `latency-metric`: the latency metric to show, possible options: "average", "min", "max", "p90", "p95", "p99", default is "average" +* `show-failing-only`: if "true" then only the failing (down) monitors will be shown +* `show-configured-only`: if "true" then only the explicitly configured monitors will be shown. Details below. + +**Explicit monitor configs:** + +Under the `options` you can specify your monitors by using their name, adding custom icons, or overwriting the links for the items (by default the Kuvasz monitor detail page will be used as a link). + +To use a custom icon, you need to use the monitor's name as the property key and then you can use any of the following for the icon: + +* Simple Icons with the `si:` prefix +* Dashboard icons with `di:` +* Material Design Icons with `mdi:` +* Self-hosted icons with `sh:` +* or a simple, direct URL to an image + +```yaml +'cnn.com': si:cnn <- using simple icons +'cnn.com-url': https://cnn.com <- overwriting the link of a given monitor on the dashboard +``` + +When `show-configured-only` is set to "true" only the monitors that has a custom icon or a custom URL will be shown on the widget! + +**YAML** + +```yaml +- type: custom-api + title: HTTP monitors + cache: 5m + options: + base-url: ${KUVASZ_HOST} + api-key: ${KUVASZ_API_KEY} + style: full + period: 1d + show-metrics: true + compact-metric: latency + latency-metric: p95 + show-failing-only: false + show-configured-only: true + 'cnn.com': si:cnn + 'cnn.com-url': https://cnn.com + 'google.de': si:google + 'DOWN monitor example-url': https://example.com + template: | + {{/* Required config options */}} + {{ $baseURL := .Options.StringOr "base-url" "" }} + + {{/* Optional config options */}} + {{ $apiKey := .Options.StringOr "api-key" "" }} + {{ $period := .Options.StringOr "period" "24h" }} + {{ $style := .Options.StringOr "style" "full" }} + {{ $showMetrics := .Options.BoolOr "show-metrics" false }} + {{ $compactMetric := .Options.StringOr "compact-metric" "uptime" }} + {{ $latencyMetric := .Options.StringOr "latency-metric" "average" }} + {{ $showFailingOnly := .Options.BoolOr "show-failing-only" false }} + {{ $showOnlyConfigured := .Options.BoolOr "show-configured-only" false }} + + {{ $monitors := newRequest (print $baseURL "/api/v2/http-monitors?enabled=true") + | withHeader "X-Api-Key" $apiKey + | getResponse }} + + {{ $options := .Options }} + {{ $displayedItems := 0 }} + + {{ if eq $style "compact" }} + + {{ else }} + + {{ end }} + + {{ if eq $displayedItems 0 }} +
+

All sites are online

+ + + +
+ {{ end }} +``` + +## Push monitors + +This one is really similar to HTTP monitors, but the latency is not relevant here. + +**Options** + +* `base-url`: your Kuvasz host (mandatory), better to set it up via the KUVASZ_HOST environment variable +* `api-key`: your own API key for Kuvasz, optional if you disabled authentication. Better to set it up via the KUVASZ_API_KEY +* `period`: an ISO-8601 interval string for the cumulative stats (incidents, affected monitors, uptime ratio), the default is 24 hours +* `show-uptime`: whether to load and display the uptime ratio, or disable it completely. Be aware, that if you would like to show metrics for a lot of monitors, it could slow down your dashboard since the metrics need to be fetched on a per monitor basis. +* `show-failing-only`: if "true" then only the failing (down) monitors will be shown +* `show-configured-only`: if "true" then only the explicitly configured monitors will be shown. The explicit monitor config is exactly the same as for the HTTP monitors. + +**Explicit monitor configs:** + +Under the `options` you can specify your monitors by using their name, explicitly enabling them, or overwriting the links for the items (by default the Kuvasz monitor detail page will be used as a link). + +```yaml +'a failing job': true <- explicitly adding the monitor to the displayed list +'a failing job-url': https://your-own-url.com <- overwriting the link for it +``` + +When `show-configured-only` is set to "true" only the monitors that has an explicit configuration entry (either for the visibility or for the URL) will be shown on the widget! + +**YAML** + +```yaml +- type: custom-api + title: Push monitors + cache: 5m + options: + base-url: ${KUVASZ_HOST} + api-key: ${KUVASZ_API_KEY} + period: 1d + show-uptime: true + show-failing-only: false + show-configured-only: false + 'a failing job': true + 'a failing job-url': https://your-own-url.com + template: | + {{/* Required config options */}} + {{ $baseURL := .Options.StringOr "base-url" "" }} + + {{/* Optional config options */}} + {{ $apiKey := .Options.StringOr "api-key" "" }} + {{ $period := .Options.StringOr "period" "24h" }} + {{ $showUptime := .Options.BoolOr "show-uptime" false }} + {{ $showFailingOnly := .Options.BoolOr "show-failing-only" false }} + {{ $showOnlyConfigured := .Options.BoolOr "show-configured-only" false }} + + {{ $monitors := newRequest (print $baseURL "/api/v2/push-monitors?enabled=true") + | withHeader "X-Api-Key" $apiKey + | getResponse }} + + {{ $options := .Options }} + {{ $displayedItems := 0 }} + + + + {{ if eq $displayedItems 0 }} +
+

All sites are online

+ + + +
+ {{ end }} +``` diff --git a/widgets/kuvasz-uptime-metrics/http-compact-preview.png b/widgets/kuvasz-uptime-metrics/http-compact-preview.png new file mode 100644 index 0000000..da07bc6 Binary files /dev/null and b/widgets/kuvasz-uptime-metrics/http-compact-preview.png differ diff --git a/widgets/kuvasz-uptime-metrics/http-stats-preview.png b/widgets/kuvasz-uptime-metrics/http-stats-preview.png new file mode 100644 index 0000000..77e7e92 Binary files /dev/null and b/widgets/kuvasz-uptime-metrics/http-stats-preview.png differ diff --git a/widgets/kuvasz-uptime-metrics/meta.yml b/widgets/kuvasz-uptime-metrics/meta.yml new file mode 100644 index 0000000..0bf43fa --- /dev/null +++ b/widgets/kuvasz-uptime-metrics/meta.yml @@ -0,0 +1,3 @@ +title: Kuvasz Uptime metrics +description: HTTP / push uptime monitor widgets using Kuvasz Uptime for backend data +author: adamkobor diff --git a/widgets/kuvasz-uptime-metrics/preview.png b/widgets/kuvasz-uptime-metrics/preview.png new file mode 100644 index 0000000..512aa71 Binary files /dev/null and b/widgets/kuvasz-uptime-metrics/preview.png differ diff --git a/widgets/kuvasz-uptime-metrics/push-preview.png b/widgets/kuvasz-uptime-metrics/push-preview.png new file mode 100644 index 0000000..879494c Binary files /dev/null and b/widgets/kuvasz-uptime-metrics/push-preview.png differ