WIP: tmux-healthchecks

Monitor your Healthchecks project from within tmux!

Warning

This repository is a work in progress, so option names etc. are likely to change any moment. Feel free to try it out though! What isn't in the TODO section has already been implemented and should work.

Features

• Responses are cached to make fewer requests

Installing

This plugin requires jq.

Installing with TPM (recommended)

1. Install TPM
2. Add this plugin to your tmux config:

   set -g @plugin "senesc/tmux-healthchecks"
   

3. Reload your config and install with prefix + I

Manual install

1. Clone this repo to the desired location;
2. Add the following line to the bottom of your config file:

   run-shell "~/path/to/repo/healthchecks.tmux"
   

3. Reload your config or restart tmux

Usage and customization

For this plugin to work, you must create a read-only API key from your project settings page, and put it in the @healthchecks_api_key variable:

set -g @healthchecks_api_key "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

There are three possible statuses to determine icons, text, styles etc.:

• Up: when all checks of the project are up
• Down: when at least one check is down
• Unknown: when the network is not reachable, the API key is missing or any error occurs.

Status bar variables

#{healthchecks_down_count}

The number of checks that are currently down.

#{healthchecks_status_icon}

An icon representing the status, by default "<3", "</3" and "?" respectively for up, down and unknown. Can be changed by setting the @healthchecks_up_icon, @healthchecks_down_icon and @healthchecks_unknown_icon options.

#{healthchecks_status_short}

A static message, by default "UP", "DOWN" or "unknown". Can be changed by setting @healthchecks_up_short, @healthchecks_down_short and @healthchecks_unknown_short.

#{healthchecks_status_details}

If at least one check is down shows its slug and how many are down in total (e.g. office-backup & 2 others). Otherwise, defaults are "all UP" and "unknown". While the down text is fixed, the latter two can be changed by setting @healthchecks_up_details and @healthchecks_unknown_details.

#{healthchecks_icon_style}

Style that should be associated with the icon, depends on current status. Defaults to the value of status-style and can be changed by setting @healthchecks_up_icon_style, @healthchecks_down_icon_style and @healthchecks_unknown_icon_style to something like "#[fg=green,bg=default,bold]".

#{healthchecks_text_style}

The same as above, except this is intended to be used with short/details text. Style options are @healthchecks_up_text_style, @healthchecks_down_text_style and @healthchecks_unknown_text_style.

---

You can use these in your config, for example, by appending them to your status-right:

set -ag status-right "#{healthchecks_icon_style}#{healthchecks_status_icon} #{healthchecks_text_style}#{healthchecks_status_details}"

Keybindings

• prefix + H to show the list of all checks along with their statuses. Can be changed by setting @healthchecks_list_key
• prefix + Alt-h to force the refresh (see Cache). Key can be changed by setting @healthchecks_update_key

Cache

Since refreshing the project status every 15 seconds (or whatever is set in your status-interval option) is kinda useless and would probably get you a 429 too many requests pretty quickly, this plugin caches the API response and sets an independent update interval:

set -g @healthchecks_update_interval [seconds]

Please note that this value can't be lower than status-interval, because the actual UI updates depend on that. The default value is 300 seconds (or 5 minutes).

With @healthchecks_cache_file you can customize where the cache is stored:

set -g @healthchecks_cache_file "/tmp/my/path"

By default, it is saved to /tmp/tmux-healthchecks- followed by the first 6 characters of your API key, which allows different tmux sessions to monitor different projects.

---

TODO:

@healthchecks_api_endpoint
@healchchecks_display_down
@healthchecks_bell_down

• make the check shown in details the latest one to go off
• implement endpoint stuff
• sane defaults
• add a bell/message whenever anything goes down
• add some kind of persistence such that when you log into tmux you get notified of checks that went down while you were offline
• test it with tpm installation
• make a catppuccin/etc. plugin compat script
• add a xdg-open healthchecks.io keybind
• how can one disable keybinds?
• add screenshots
• correct whatever bug creates the /tmp/tmux-healthchecks- file