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 @@
1
+dist/
1 2
 osem_notify
2 3
 osem_notify.exe

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

@@ -0,0 +1,56 @@
1
+#!/bin/bash
2
+
3
+release=$1
4
+if [ -z "$release" ]; then
5
+    echo "usage:   .scripts/build_crossplatform.sh <release name>"
6
+    exit 1
7
+fi
8
+
9
+export GOPATH=$HOME/.go
10
+
11
+echo go version
12
+
13
+rm -rf dist
14
+mkdir dist
15
+
16
+export GOOS=linux
17
+export GOARCH=386
18
+go get -v -d ./
19
+go build ./
20
+mv osem_notify dist/osem_notify_${release}_linux32
21
+export GOARCH=amd64
22
+go get -v -d ./
23
+go build ./
24
+mv osem_notify dist/osem_notify_${release}_linux64
25
+
26
+export GOOS=windows
27
+export GOARCH=386
28
+go get -v -d ./
29
+go build ./
30
+mv osem_notify.exe dist/osem_notify_${release}_win32.exe
31
+export GOARCH=amd64
32
+go get -v -d ./
33
+go build ./
34
+mv osem_notify.exe dist/osem_notify_${release}_win64.exe
35
+
36
+export GOOS=darwin
37
+export GOARCH=386
38
+go get -v -d ./
39
+go build ./
40
+mv osem_notify dist/osem_notify_${release}_mac32
41
+export GOARCH=amd64
42
+go get -v -d ./
43
+go build ./
44
+mv osem_notify dist/osem_notify_${release}_mac64
45
+
46
+export GOOS=linux
47
+export GOARCH=arm
48
+go get -v -d ./
49
+go build ./
50
+mv osem_notify dist/osem_notify_${release}_linux_arm
51
+
52
+export GOOS=android
53
+export GOARCH=arm
54
+go get -v -d ./
55
+go build ./
56
+mv osem_notify dist/osem_notify_${release}_android

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

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

+ 15
- 0
.travis.yml View File

@@ -0,0 +1,15 @@
1
+language: go
2
+
3
+go:
4
+  - "1.x"
5
+
6
+script: ".scripts/build_crossplatform $TRAVIS_TAG"
7
+
8
+deploy:
9
+  provider: releases
10
+  api_key: "$GITHUB_OAUTH_TOKEN"
11
+  file_glob: true
12
+  file: dist/*
13
+  skip_cleanup: true
14
+  on:
15
+    tags: true

+ 101
- 0
README.md View File

@@ -0,0 +1,101 @@
1
+# osem_notify 🔆🌡📡📈  ⚠ 📲
2
+
3
+Cross platform command line application to run health checks against sensor stations registered on [openSenseMap.org](https://opensensemap.org).
4
+
5
+This tool quickly runs various health checks on selected senseBoxes,
6
+and can send out notifications via various protocols.
7
+Specifically email is implemented, but other transports can be added easily.
8
+
9
+The tool can also operate in watch mode, checking boxes at regular intervals.
10
+
11
+Check the manual in the [doc/](doc/osem_notify.md) directory for a description of features.
12
+
13
+## get it
14
+Download a build from the [releases page](releases/).
15
+You can immediately call the application by running `./osem_notify` in a terminal in your downloads directory.
16
+
17
+On unix platforms you may add it to your path for convenience, so it is always callable via `osem_notify`:
18
+```sh
19
+sudo mv osem_notify /usr/bin/osem_notify
20
+```
21
+
22
+## configure it
23
+Configuration is required to set up notification transports, and can set the default healthchecks.
24
+Configuration can be done via a YAML file located at `~/.osem_notify.yml` or through environment variables.
25
+Example configuration:
26
+
27
+```yaml
28
+defaultHealthchecks:
29
+  notifications:
30
+    transport: email
31
+    options:
32
+      recipients:
33
+      - fridolina@example.com
34
+      - ruth.less@example.com
35
+  events:
36
+    - type: "measurement_age"
37
+      target: "all"    # all sensors
38
+      threshold: "15m" # any duration
39
+    - type: "measurement_faulty"
40
+      target: "all"
41
+      threshold: ""
42
+
43
+# only needed when sending notifications via email
44
+email:
45
+  host: smtp.example.com
46
+  port: 25
47
+  user: foo
48
+  pass: bar
49
+  from: hildegunst@example.com
50
+```
51
+
52
+### possible values for `notifications`:
53
+`transport` | `options`
54
+------------|------------
55
+`email`     | `recipients`: list of email addresses
56
+
57
+Want more? [add it](#contribute)!
58
+
59
+### possible values for `events[]`:
60
+
61
+`type`               | description
62
+---------------------|------------
63
+`measurement_age`    | Alert when sensor `target` has not submitted measurements within `threshold` duration.
64
+`measurement_faulty` | Alert when sensor `target`'s last reading was a presumably faulty value (e.g. broken / disconnected sensor).
65
+`measurement_min`    | Alert when sensor `target`'s last measurement is lower than `threshold`.
66
+`measurement_max`    | Alert when sensor `target`'s last measurement is higher than `threshold`.
67
+
68
+`target` can be either a sensor ID, or `"all"` to match all sensors of the box.
69
+`threshold` must be a string.
70
+
71
+### configuration via environment variables
72
+Instead of a YAML file, you may configure the tool through environment variables. Keys are the same as in the YAML, but:
73
+
74
+- prefixed with `osem_notify_`
75
+- path separator is not `.`, but `_`
76
+
77
+Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes`
78
+
79
+## build it
80
+Want to use `osem_notify` on a platform where no builds are provided?
81
+
82
+Assuming you have golang installed, run
83
+```sh
84
+go get -v -d ./
85
+go build ./
86
+```
87
+
88
+For cross-compilation, check [this guide](https://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5) out.
89
+
90
+## contribute
91
+Contributions are welcome!
92
+Check out the following locations for plugging in new functionality:
93
+
94
+- new notification transports: [core/notifiers.go](core/notifiers.go)
95
+- new health checks: [core/Box.go](core/Box.go)
96
+- new commands: [cmd/](cmd/)
97
+
98
+Before committing and submitting a pull request, please run `go fmt ./ cmd/ core/`.
99
+
100
+## license
101
+GPL-3.0 Norwin Roosen

+ 29
- 0
doc/osem_notify.md View File

@@ -0,0 +1,29 @@
1
+## osem_notify
2
+
3
+Root command displaying help
4
+
5
+### Synopsis
6
+
7
+Run healthchecks and send notifications for boxes on opensensemap.org
8
+
9
+```
10
+osem_notify [flags]
11
+```
12
+
13
+### Options
14
+
15
+```
16
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
17
+  -d, --debug              enable verbose logging
18
+  -h, --help               help for osem_notify
19
+  -l, --logformat string   log format, can be plain or json (default "plain")
20
+  -n, --notify             if set, will send out notifications.
21
+                           Otherwise results are printed to stdout only
22
+```
23
+
24
+### SEE ALSO
25
+
26
+* [osem_notify check](osem_notify_check.md)	 - One-off check for events on boxes
27
+* [osem_notify watch](osem_notify_watch.md)	 - Watch boxes for events at an interval
28
+
29
+###### Auto generated by spf13/cobra on 24-Jun-2018

+ 30
- 0
doc/osem_notify_check.md View File

@@ -0,0 +1,30 @@
1
+## osem_notify check
2
+
3
+One-off check for events on boxes
4
+
5
+### Synopsis
6
+
7
+One-off check for events on boxes
8
+
9
+### Options
10
+
11
+```
12
+  -h, --help   help for check
13
+```
14
+
15
+### Options inherited from parent commands
16
+
17
+```
18
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
19
+  -d, --debug              enable verbose logging
20
+  -l, --logformat string   log format, can be plain or json (default "plain")
21
+  -n, --notify             if set, will send out notifications.
22
+                           Otherwise results are printed to stdout only
23
+```
24
+
25
+### SEE ALSO
26
+
27
+* [osem_notify](osem_notify.md)	 - Root command displaying help
28
+* [osem_notify check boxes](osem_notify_check_boxes.md)	 - one-off check on one or more box IDs
29
+
30
+###### Auto generated by spf13/cobra on 24-Jun-2018

+ 33
- 0
doc/osem_notify_check_boxes.md View File

@@ -0,0 +1,33 @@
1
+## osem_notify check boxes
2
+
3
+one-off check on one or more box IDs
4
+
5
+### Synopsis
6
+
7
+specify box IDs to check them for events
8
+
9
+```
10
+osem_notify check boxes <boxId> [...<boxIds>] [flags]
11
+```
12
+
13
+### Options
14
+
15
+```
16
+  -h, --help   help for boxes
17
+```
18
+
19
+### Options inherited from parent commands
20
+
21
+```
22
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
23
+  -d, --debug              enable verbose logging
24
+  -l, --logformat string   log format, can be plain or json (default "plain")
25
+  -n, --notify             if set, will send out notifications.
26
+                           Otherwise results are printed to stdout only
27
+```
28
+
29
+### SEE ALSO
30
+
31
+* [osem_notify check](osem_notify_check.md)	 - One-off check for events on boxes
32
+
33
+###### Auto generated by spf13/cobra on 24-Jun-2018

+ 31
- 0
doc/osem_notify_watch.md View File

@@ -0,0 +1,31 @@
1
+## osem_notify watch
2
+
3
+Watch boxes for events at an interval
4
+
5
+### Synopsis
6
+
7
+Watch boxes for events at an interval
8
+
9
+### Options
10
+
11
+```
12
+  -h, --help           help for watch
13
+  -i, --interval int   interval to run checks in minutes (default 15)
14
+```
15
+
16
+### Options inherited from parent commands
17
+
18
+```
19
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
20
+  -d, --debug              enable verbose logging
21
+  -l, --logformat string   log format, can be plain or json (default "plain")
22
+  -n, --notify             if set, will send out notifications.
23
+                           Otherwise results are printed to stdout only
24
+```
25
+
26
+### SEE ALSO
27
+
28
+* [osem_notify](osem_notify.md)	 - Root command displaying help
29
+* [osem_notify watch boxes](osem_notify_watch_boxes.md)	 - watch a list of box IDs for events
30
+
31
+###### Auto generated by spf13/cobra on 24-Jun-2018

+ 34
- 0
doc/osem_notify_watch_boxes.md View File

@@ -0,0 +1,34 @@
1
+## osem_notify watch boxes
2
+
3
+watch a list of box IDs for events
4
+
5
+### Synopsis
6
+
7
+specify box IDs to watch them for events
8
+
9
+```
10
+osem_notify watch boxes <boxId> [...<boxIds>] [flags]
11
+```
12
+
13
+### Options
14
+
15
+```
16
+  -h, --help   help for boxes
17
+```
18
+
19
+### Options inherited from parent commands
20
+
21
+```
22
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
23
+  -d, --debug              enable verbose logging
24
+  -i, --interval int       interval to run checks in minutes (default 15)
25
+  -l, --logformat string   log format, can be plain or json (default "plain")
26
+  -n, --notify             if set, will send out notifications.
27
+                           Otherwise results are printed to stdout only
28
+```
29
+
30
+### SEE ALSO
31
+
32
+* [osem_notify watch](osem_notify_watch.md)	 - Watch boxes for events at an interval
33
+
34
+###### Auto generated by spf13/cobra on 24-Jun-2018

+ 0
- 5
run.sh View File

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

Loading…
Cancel
Save