opensensemap
/
osem_notify
1
0
Fork 0
Code Issues Pull Requests Releases Activity

update readme, update docs

Browse Source
develop
noerw 6 years ago
parent 13d7aea17b
commit 9c063a4659
9 changed files with 158 additions and 24 deletions
Show Stats Download Patch File Download Diff File

36
README.md
Unescape Escape View File

@ -2,29 +2,36 @@
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.
This tool lets you automatically check if senseBoxes are still runnning correctly,
and when that's not the case, notifies you.
Currently, email notifications are implemented, but other transports can be added easily.
Implemented health checks are [described below](#possible-values-for-defaulthealthchecksevents), and new ones can be added just as easily (given some knowledge of programming).
The tool can also operate in watch mode, checking boxes at regular intervals.
The tool has multiple modes of operation:
Check the manual in the [doc/](doc/osem_notify.md) directory for a description of features.
- `osem_notify check boxes`: run one-off checks on boxes
- `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.
## 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.
Download a build from the [releases page](https://github.com/noerw/osem_notify/releases/).
You can run 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`:
On unix platforms you may need to make it executable, and can add it to your `$PATH` for convenience, so it is always callable via `osem_notify`:
```sh
sudo mv osem_notify /usr/bin/osem_notify
chmod +x osem_notify*
sudo mv osem_notify* /usr/bin/osem_notify
```
## configure it
Configuration is required to set up notification transports, and can set the default healthchecks.
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
@ -49,14 +56,14 @@ email:
from: hildegunst@example.com
```
### possible values for `notifications`:
### possible values for `defaultHealthchecks.notifications`:
`transport` | `options`
------------|------------
`email` | `recipients`: list of email addresses
Want more? [add it](#contribute)!
### possible values for `events[]`:
### possible values for `defaultHealthchecks.events[]`:
`type` | description
---------------------|------------
@ -71,8 +78,9 @@ Want more? [add it](#contribute)!
### 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_`
- prefixed with `OSEM_NOTIFY_`
- path separator is not `.`, but `_`
- all upper case
Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes`
@ -92,7 +100,7 @@ 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 health checks: [core/healthcheck*.go](core/healtchecks.go)
- new commands: [cmd/](cmd/)
Before committing and submitting a pull request, please run `go fmt ./ cmd/ core/`.

9
doc/osem_notify.md → docs/osem_notify.md
Unescape Escape View File

@ -13,17 +13,22 @@ osem_notify [flags]
### Options
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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
Otherwise results are printed to stdout only.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
* [osem_notify check](osem_notify_check.md) - One-off check for events on boxes
* [osem_notify debug](osem_notify_debug.md) - Run some debugging checks on osem_notify itself
* [osem_notify version](osem_notify_version.md) - Get build and version information
* [osem_notify watch](osem_notify_watch.md) - Watch boxes for events at an interval
###### Auto generated by spf13/cobra on 24-Jun-2018
###### Auto generated by spf13/cobra on 26-Jun-2018

7
doc/osem_notify_check.md → docs/osem_notify_check.md
Unescape Escape View File

@ -15,11 +15,14 @@ One-off check for events on boxes
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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
Otherwise results are printed to stdout only.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
@ -27,4 +30,4 @@ One-off check for events on boxes
* [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
###### Auto generated by spf13/cobra on 26-Jun-2018

7
doc/osem_notify_check_boxes.md → docs/osem_notify_check_boxes.md
Unescape Escape View File

@ -19,15 +19,18 @@ osem_notify check boxes <boxId> [...<boxIds>] [flags]
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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
Otherwise results are printed to stdout only.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### 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
###### Auto generated by spf13/cobra on 26-Jun-2018

37
docs/osem_notify_debug.md
Unescape Escape View File

@ -0,0 +1,37 @@
## osem_notify debug
Run some debugging checks on osem_notify itself
### Synopsis
osem_notify debug <feature> tests the functionality of the given feature
```
osem_notify debug [flags]
```
### Options
```
-h, --help help for debug
```
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
* [osem_notify](osem_notify.md) - Root command displaying help
* [osem_notify debug notifications](osem_notify_debug_notifications.md) - Verify that notifications are working
###### Auto generated by spf13/cobra on 26-Jun-2018

36
docs/osem_notify_debug_notifications.md
Unescape Escape View File

@ -0,0 +1,36 @@
## osem_notify debug notifications
Verify that notifications are working
### Synopsis
osem_notify debug <feature> tests the functionality of the given feature
```
osem_notify debug notifications [flags]
```
### Options
```
-h, --help help for notifications
```
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
* [osem_notify debug](osem_notify_debug.md) - Run some debugging checks on osem_notify itself
###### Auto generated by spf13/cobra on 26-Jun-2018

36
docs/osem_notify_version.md
Unescape Escape View File

@ -0,0 +1,36 @@
## osem_notify version
Get build and version information
### Synopsis
osem_notify version returns its build and version information
```
osem_notify version [flags]
```
### Options
```
-h, --help help for version
```
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
* [osem_notify](osem_notify.md) - Root command displaying help
###### Auto generated by spf13/cobra on 26-Jun-2018

7
doc/osem_notify_watch.md → docs/osem_notify_watch.md
Unescape Escape View File

@ -16,11 +16,14 @@ Watch boxes for events at an interval
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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
Otherwise results are printed to stdout only.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### SEE ALSO
@ -28,4 +31,4 @@ Watch boxes for events at an interval
* [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
###### Auto generated by spf13/cobra on 26-Jun-2018

7
doc/osem_notify_watch_boxes.md → docs/osem_notify_watch_boxes.md
Unescape Escape View File

@ -19,16 +19,19 @@ osem_notify watch boxes <boxId> [...<boxIds>] [flags]
### Options inherited from parent commands
```
-a, --api string openSenseMap API to query against (default "https://api.opensensemap.org")
-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
Otherwise results are printed to stdout only.
You might want to run 'osem_notify debug notifications' first to verify everything works.
```
### 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
###### Auto generated by spf13/cobra on 26-Jun-2018
Write Preview
Loading…
Cancel
Save