From bc8f02e0a92c5b7bc50b23cb0605e3671bb79232 Mon Sep 17 00:00:00 2001 From: noerw Date: Tue, 26 Jun 2018 23:56:28 +0200 Subject: [PATCH] embed config help in build --- README.md | 63 +++++++++---------------------------------- cmd/root.go | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++- cmd/watch.go | 2 +- 3 files changed, 87 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 71688e7..e6278ab 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Implemented health checks are [described below](#possible-values-for-defaultheal The tool has multiple modes of operation: - `osem_notify check boxes`: run one-off checks on boxes -- `osem_notify watch boxes`: check boxes continuously +- `osem_notify watch boxes`: check boxes continuously. Run `osem_notify help` or check the manual in the [docs/](docs/osem_notify.md) directory for more details. @@ -26,63 +26,24 @@ sudo mv osem_notify* /usr/bin/osem_notify ## configure it The tool works out of the box for basic functionality, but must be configured to set up notifications. - Configuration can be done via a YAML file located at `~/.osem_notify.yml` or through environment variables. -Example configuration: - -```yaml -# override default health checks: -defaultHealthchecks: - notifications: - transport: email - options: - recipients: - - fridolina@example.com - - ruth.less@example.com - events: - - type: "measurement_age" - target: "all" # all sensors - threshold: "15m" # any duration - - type: "measurement_faulty" - target: "all" - threshold: "" - -# only needed when sending notifications via email -email: - host: smtp.example.com - port: 25 - user: foo - pass: bar - from: hildegunst@example.com -``` - -### possible values for `defaultHealthchecks.notifications`: -`transport` | `options` -------------|------------ -`email` | `recipients`: list of email addresses - -Want more? [add it](#contribute)! +Run `osem_notify help config` for details and an example configuration. -### possible values for `defaultHealthchecks.events[]`: +### available healthchecks `type` | description ---------------------|------------ -`measurement_age` | Alert when sensor `target` has not submitted measurements within `threshold` duration. -`measurement_faulty` | Alert when sensor `target`'s last reading was a presumably faulty value (e.g. broken / disconnected sensor). -`measurement_min` | Alert when sensor `target`'s last measurement is lower than `threshold`. -`measurement_max` | Alert when sensor `target`'s last measurement is higher than `threshold`. - -`target` can be either a sensor ID, or `"all"` to match all sensors of the box. -`threshold` must be a string. +`measurement_age` | Alert when a sensor has not submitted measurements within a given duration. +`measurement_faulty` | Alert when a sensor's last reading was a presumably faulty value (e.g. broken / disconnected sensor). +`measurement_min` | Alert when a sensor's last measurement is lower than a given value. +`measurement_max` | Alert when a sensor's last measurement is higher than a given value. -### configuration via environment variables -Instead of a YAML file, you may configure the tool through environment variables. Keys are the same as in the YAML, but: - -- prefixed with `OSEM_NOTIFY_` -- path separator is not `.`, but `_` -- all upper case +### available notification transports +`transport` | `options` +------------|------------ +`email` | `recipients`: list of email addresses -Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes` +Want more? [add it](#contribute)! ## build it Want to use `osem_notify` on a platform where no builds are provided? diff --git a/cmd/root.go b/cmd/root.go index 5b19c9b..eb88a7a 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -6,8 +6,75 @@ import ( log "github.com/sirupsen/logrus" "github.com/spf13/cobra" "github.com/spf13/viper" + + "github.com/noerw/osem_notify/utils" ) +var configHelpCmd = &cobra.Command{ + Use: "config", + Short: "How to configure osem_notify", + Long: `osem_notify works out of the box for basic functionality, but uses configuration to + set up notification transports and healthchecks. Additionally, all command line flags can + be set to default values through the configuration. + + Configuration can be set either through a YAML file, or through environment variables. + You can use different configuration files per call by settings the --config flag. + + +> Example configuration: + + # override default health checks: + defaultHealthchecks: + notifications: + transport: email + options: + recipients: + - fridolina@example.com + - ruth.less@example.com + events: + - type: "measurement_age" + target: "all" # all sensors + threshold: "15m" # any duration + - type: "measurement_faulty" + target: "all" + threshold: "" + + # only needed when sending notifications via email + email: + host: smtp.example.com + port: 25 + user: foo + pass: bar + from: hildegunst@example.com + + +> possible values for defaultHealthchecks.notifications: + + transport | options + ----------|------------------------------------- + email | recipients: list of email addresses + + +> possible values for defaultHealthchecks.events[]: + + type | description + -------------------|--------------------------------------------------- + measurement_age | Alert when sensor target has not submitted measurements within threshold duration. + measurement_faulty | Alert when sensor target's last reading was a presumably faulty value (e.g. broken / disconnected sensor). + measurement_min | Alert when sensor target's last measurement is lower than threshold. + measurement_max | Alert when sensor target's last measurement is higher than threshold. + + - target can be either a sensor ID, or "all" to match all sensors of the box. + - threshold must be a string. + +> configuration via environment variables + + Instead of a YAML file, you may configure the tool through environment variables. Keys are the same as in the YAML, but: + keys are prefixed with "OSEM_NOTIFY_", path separator is not ".", but "_", all upper case + + Example: OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes`, +} + var rootCmd = &cobra.Command{ Use: "osem_notify", Short: "Root command displaying help", @@ -50,12 +117,18 @@ func init() { rootCmd.PersistentFlags().StringVarP(&api, "api", "a", "https://api.opensensemap.org", "openSenseMap API to query against") rootCmd.PersistentFlags().StringVarP(&logFormat, "logformat", "l", "plain", "log format, can be plain or json") rootCmd.PersistentFlags().BoolVarP(&debug, "debug", "d", false, "enable verbose logging") - rootCmd.PersistentFlags().BoolVarP(&shouldNotify, "notify", "n", false, `if set, will send out notifications. + rootCmd.PersistentFlags().BoolVarP(&shouldNotify, "notify", "n", false, `if set, will send out notifications, Otherwise results are printed to stdout only. You might want to run 'osem_notify debug notifications' first to verify everything works. + +Notifications for failing checks are sent only once, +and then cached until the issue got resolved. +To clear the cache, delete the file ~/.osem_notify_cache.yaml. `) viper.BindPFlags(rootCmd.PersistentFlags()) // let flags override config + + rootCmd.AddCommand(configHelpCmd) } func Execute() { diff --git a/cmd/watch.go b/cmd/watch.go index ea0c4fd..471fba7 100644 --- a/cmd/watch.go +++ b/cmd/watch.go @@ -14,7 +14,7 @@ func init() { watchInterval int ) - watchCmd.PersistentFlags().IntVarP(&watchInterval, "interval", "i", 15, "interval to run checks in minutes") + watchCmd.PersistentFlags().IntVarP(&watchInterval, "interval", "i", 30, "interval to run checks in minutes") viper.BindPFlags(watchCmd.PersistentFlags()) watchCmd.AddCommand(watchBoxesCmd)