add readme, docs, travis

develop v1.0.0
noerw 6 年前
父节点 f1cc1bd8d6
当前提交 a122b3e3fe

1
.gitignore vendored

@ -1,2 +1,3 @@
dist/
osem_notify
osem_notify.exe

@ -0,0 +1,56 @@
#!/bin/bash
release=$1
if [ -z "$release" ]; then
echo "usage: .scripts/build_crossplatform.sh <release name>"
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

@ -0,0 +1,4 @@
#!/bin/bash
go fmt ./ ./cmd/ ./core/ && go build ./ && \
./osem_notify check boxes \
593bcd656ccf3b0011791f5a 5b26181b1fef04001b69093c 59b31b8dd67eb50011165a04 562bdcf3b3de1fe005e03d2a $@

@ -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

@ -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

@ -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

@ -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

@ -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 <boxId> [...<boxIds>] [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

@ -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

@ -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 <boxId> [...<boxIds>] [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

@ -1,5 +0,0 @@
go fmt ./ ./cmd/ ./core/ && \
go build ./ && \
./osem_notify check boxes \
593bcd656ccf3b0011791f5a 5b26181b1fef04001b69093c 59b31b8dd67eb50011165a04 562bdcf3b3de1fe005e03d2a $@ \
--log-level debug
正在加载...
取消
保存