diff --git a/.gitignore b/.gitignore index 262fbc8..8985839 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ +dist/ osem_notify osem_notify.exe diff --git a/.scripts/build_crossplatform.sh b/.scripts/build_crossplatform.sh new file mode 100755 index 0000000..0baab67 --- /dev/null +++ b/.scripts/build_crossplatform.sh @@ -0,0 +1,56 @@ +#!/bin/bash + +release=$1 +if [ -z "$release" ]; then + echo "usage: .scripts/build_crossplatform.sh " + exit 1 +fi + +export GOPATH=$HOME/.go + +echo go version + +rm -rf dist +mkdir dist + +export GOOS=linux +export GOARCH=386 +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_linux32 +export GOARCH=amd64 +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_linux64 + +export GOOS=windows +export GOARCH=386 +go get -v -d ./ +go build ./ +mv osem_notify.exe dist/osem_notify_${release}_win32.exe +export GOARCH=amd64 +go get -v -d ./ +go build ./ +mv osem_notify.exe dist/osem_notify_${release}_win64.exe + +export GOOS=darwin +export GOARCH=386 +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_mac32 +export GOARCH=amd64 +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_mac64 + +export GOOS=linux +export GOARCH=arm +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_linux_arm + +export GOOS=android +export GOARCH=arm +go get -v -d ./ +go build ./ +mv osem_notify dist/osem_notify_${release}_android diff --git a/.scripts/run.sh b/.scripts/run.sh new file mode 100755 index 0000000..e1d99e3 --- /dev/null +++ b/.scripts/run.sh @@ -0,0 +1,4 @@ +#!/bin/bash +go fmt ./ ./cmd/ ./core/ && go build ./ && \ + ./osem_notify check boxes \ + 593bcd656ccf3b0011791f5a 5b26181b1fef04001b69093c 59b31b8dd67eb50011165a04 562bdcf3b3de1fe005e03d2a $@ diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..a8dd958 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,15 @@ +language: go + +go: + - "1.x" + +script: ".scripts/build_crossplatform $TRAVIS_TAG" + +deploy: + provider: releases + api_key: "$GITHUB_OAUTH_TOKEN" + file_glob: true + file: dist/* + skip_cleanup: true + on: + tags: true diff --git a/README.md b/README.md new file mode 100644 index 0000000..37ab3dc --- /dev/null +++ b/README.md @@ -0,0 +1,101 @@ +# osem_notify 🔆🌡📡📈 ⚠ 📲 + +Cross platform command line application to run health checks against sensor stations registered on [openSenseMap.org](https://opensensemap.org). + +This tool quickly runs various health checks on selected senseBoxes, +and can send out notifications via various protocols. +Specifically email is implemented, but other transports can be added easily. + +The tool can also operate in watch mode, checking boxes at regular intervals. + +Check the manual in the [doc/](doc/osem_notify.md) directory for a description of features. + +## get it +Download a build from the [releases page](releases/). +You can immediately call the application by running `./osem_notify` in a terminal in your downloads directory. + +On unix platforms you may add it to your path for convenience, so it is always callable via `osem_notify`: +```sh +sudo mv osem_notify /usr/bin/osem_notify +``` + +## configure it +Configuration is required to set up notification transports, and can set the default healthchecks. +Configuration can be done via a YAML file located at `~/.osem_notify.yml` or through environment variables. +Example configuration: + +```yaml +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 `notifications`: +`transport` | `options` +------------|------------ +`email` | `recipients`: list of email addresses + +Want more? [add it](#contribute)! + +### possible values for `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: + +- prefixed with `osem_notify_` +- path separator is not `.`, but `_` + +Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes` + +## build it +Want to use `osem_notify` on a platform where no builds are provided? + +Assuming you have golang installed, run +```sh +go get -v -d ./ +go build ./ +``` + +For cross-compilation, check [this guide](https://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5) out. + +## contribute +Contributions are welcome! +Check out the following locations for plugging in new functionality: + +- new notification transports: [core/notifiers.go](core/notifiers.go) +- new health checks: [core/Box.go](core/Box.go) +- new commands: [cmd/](cmd/) + +Before committing and submitting a pull request, please run `go fmt ./ cmd/ core/`. + +## license +GPL-3.0 Norwin Roosen diff --git a/doc/osem_notify.md b/doc/osem_notify.md new file mode 100644 index 0000000..cd95100 --- /dev/null +++ b/doc/osem_notify.md @@ -0,0 +1,29 @@ +## osem_notify + +Root command displaying help + +### Synopsis + +Run healthchecks and send notifications for boxes on opensensemap.org + +``` +osem_notify [flags] +``` + +### Options + +``` + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -h, --help help for osem_notify + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only +``` + +### SEE ALSO + +* [osem_notify check](osem_notify_check.md) - One-off check for events on boxes +* [osem_notify watch](osem_notify_watch.md) - Watch boxes for events at an interval + +###### Auto generated by spf13/cobra on 24-Jun-2018 diff --git a/doc/osem_notify_check.md b/doc/osem_notify_check.md new file mode 100644 index 0000000..5494cdf --- /dev/null +++ b/doc/osem_notify_check.md @@ -0,0 +1,30 @@ +## osem_notify check + +One-off check for events on boxes + +### Synopsis + +One-off check for events on boxes + +### Options + +``` + -h, --help help for check +``` + +### Options inherited from parent commands + +``` + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only +``` + +### SEE ALSO + +* [osem_notify](osem_notify.md) - Root command displaying help +* [osem_notify check boxes](osem_notify_check_boxes.md) - one-off check on one or more box IDs + +###### Auto generated by spf13/cobra on 24-Jun-2018 diff --git a/doc/osem_notify_check_boxes.md b/doc/osem_notify_check_boxes.md new file mode 100644 index 0000000..2182c33 --- /dev/null +++ b/doc/osem_notify_check_boxes.md @@ -0,0 +1,33 @@ +## osem_notify check boxes + +one-off check on one or more box IDs + +### Synopsis + +specify box IDs to check them for events + +``` +osem_notify check boxes [...] [flags] +``` + +### Options + +``` + -h, --help help for boxes +``` + +### Options inherited from parent commands + +``` + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only +``` + +### SEE ALSO + +* [osem_notify check](osem_notify_check.md) - One-off check for events on boxes + +###### Auto generated by spf13/cobra on 24-Jun-2018 diff --git a/doc/osem_notify_watch.md b/doc/osem_notify_watch.md new file mode 100644 index 0000000..3c22345 --- /dev/null +++ b/doc/osem_notify_watch.md @@ -0,0 +1,31 @@ +## osem_notify watch + +Watch boxes for events at an interval + +### Synopsis + +Watch boxes for events at an interval + +### Options + +``` + -h, --help help for watch + -i, --interval int interval to run checks in minutes (default 15) +``` + +### Options inherited from parent commands + +``` + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only +``` + +### SEE ALSO + +* [osem_notify](osem_notify.md) - Root command displaying help +* [osem_notify watch boxes](osem_notify_watch_boxes.md) - watch a list of box IDs for events + +###### Auto generated by spf13/cobra on 24-Jun-2018 diff --git a/doc/osem_notify_watch_boxes.md b/doc/osem_notify_watch_boxes.md new file mode 100644 index 0000000..222cdb9 --- /dev/null +++ b/doc/osem_notify_watch_boxes.md @@ -0,0 +1,34 @@ +## osem_notify watch boxes + +watch a list of box IDs for events + +### Synopsis + +specify box IDs to watch them for events + +``` +osem_notify watch boxes [...] [flags] +``` + +### Options + +``` + -h, --help help for boxes +``` + +### Options inherited from parent commands + +``` + -c, --config string path to config file (default $HOME/.osem_notify.yml) + -d, --debug enable verbose logging + -i, --interval int interval to run checks in minutes (default 15) + -l, --logformat string log format, can be plain or json (default "plain") + -n, --notify if set, will send out notifications. + Otherwise results are printed to stdout only +``` + +### SEE ALSO + +* [osem_notify watch](osem_notify_watch.md) - Watch boxes for events at an interval + +###### Auto generated by spf13/cobra on 24-Jun-2018 diff --git a/run.sh b/run.sh deleted file mode 100755 index 4020f67..0000000 --- a/run.sh +++ /dev/null @@ -1,5 +0,0 @@ -go fmt ./ ./cmd/ ./core/ && \ - go build ./ && \ - ./osem_notify check boxes \ - 593bcd656ccf3b0011791f5a 5b26181b1fef04001b69093c 59b31b8dd67eb50011165a04 562bdcf3b3de1fe005e03d2a $@ \ - --log-level debug