Browse Source

add readme, docs, travis

tags/v1.0.0
noerw 1 year ago
parent
commit
a122b3e3fe

+ 1
- 0
.gitignore View File

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

+ 56
- 0
.scripts/build_crossplatform.sh View File

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

+ 4
- 0
.scripts/run.sh View File

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

+ 15
- 0
.travis.yml View File

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

+ 101
- 0
README.md View File

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

+ 29
- 0
doc/osem_notify.md View File

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

+ 30
- 0
doc/osem_notify_check.md View File

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

+ 33
- 0
doc/osem_notify_check_boxes.md View File

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

+ 31
- 0
doc/osem_notify_watch.md View File

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

+ 34
- 0
doc/osem_notify_watch_boxes.md View File

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

+ 0
- 5
run.sh View File

@@ -1,5 +0,0 @@
go fmt ./ ./cmd/ ./core/ && \
go build ./ && \
./osem_notify check boxes \
593bcd656ccf3b0011791f5a 5b26181b1fef04001b69093c 59b31b8dd67eb50011165a04 562bdcf3b3de1fe005e03d2a $@ \
--log-level debug

Loading…
Cancel
Save