Improve README and configuration

New: - Provide possibility to configure the service by environment variables for easy configuration in dockerized environments. Priority is: 1. Environment variables 2. Configuration file - README contains now the different metrics provided as well as configuration hints as well as docker things.
monofox · Apr 14, 2024 · 1fac3eb · 1fac3eb
1 parent c7b826e
commit 1fac3eb
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,39 @@ monit_exporter periodically scrapes the monit status and provides its data via H
 
 ### Features
 
+#### Exported metrics
+
+These metrics are exported by `monit_exporter`:
+
+| name                                   | description                                                                                                                                                                                                                                        |
+|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| monit_service_check                    | Monit service check info with following labels provided:<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`monitored`</dt><dd>Specifies, if the service is monitored or not, whereas `0` means no and `1` means yes.</dd><dt>`type`</dt><dd>Specifies the type of service.</dd></dl>
+| monit_service_cpu_perc                 | Monit service CPU info with following labels:<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`type`</dt><dd>Specifies value type whereas value can be `percentage` or `percentage_total`</dd></dl>
+| monit_service_mem_bytes                | Monit service mem info with following labels:<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`type`</dt><dd>Specifies value type whereas value can be `kilobyte` or `kilobyte_total`</dd></dl>
+| monit_service_network_link_state       | Monit service link states<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd></dl><br>Value can be either `-1` = Not available, `0` = down and `1` = up
+| monit_service_network_link_statistics  | Monit service link statistics<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`direction`</dt><dd>Specifies link direction (upload / download)</dd><dt>`unit`</dt><dd>Spcifies unit of metrics (bytes, errors, packets)</dd><dt>`type`</dt><dd>Specifies the type with either now or total. Whereas now means "per second"</dd></dl>
+| monit_service_port_response_times      | Monit service port checks response times<br><dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`hostname`</dt><dd>Specifies hostname checked</dd><dt>`port`</dt><dd>Specifies port to check</dd><dt>`protocol`</dt><dd>Specifies protocol used for checking service (e.g. POP, IMAP, REDIS, etc.). Default is a RAW check.</dd><dt>`type`</dt><dd>Specifies protocol type (e.g. TCP, UDP, etc.)</dd></dl>
+| monit_service_read_bytes               | Monit service Disk Read Bytes<dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`type`</dt><dd>Specifies type of read / write. Possible values: read_count, read_count_total. Value is given in bytes.</dd></dl>
+| monit_service_write_bytes              | Monit service Disk Writes Bytes<dl><dt>`check_name`</dt><dd>Name of monit check</dd><dt>`type`</dt><dd>Specifies type of read / write. Possible values: write_count, write_count_total. Value is given in bytes.</dd></dl>
+| monit_up                               | Monit status availability. `0` = not available and `1` = available
+
+
+#### Service types
+
+Services type provided correspond to the XML structure of monit:
+
+| type id | type name  |
+|---------|------------|
+| 0       | filesystem |
+| 1       | directory  |
+| 2       | file       |
+| 3       | process    |
+| 4       | host       |
+| 5       | system     |
+| 6       | fifo       |
+| 7       | program    |
+| 8       | network    |
+
 ### Support
 
 ### Dependencies
@@ -48,13 +81,41 @@ This application has the following build requirements:
 
 ### Installation
 
+#### From source
+
 To build the application from source, simply run the following commands:
 ```
-git clone https://github.com/liv-io/monit_exporter.git
+git clone https://github.com/monofox/monit_exporter.git
 cd monit_exporter
 go build
 ```
 
+#### Docker Image
+
+The preferred way to use `monit_exporter` is by running the provided Docker image. It is currently provided on GitHub Container Registry:
+
+- [`ghcr.io/monofox/monit_exporter`](https://github.com/monofox/monit_exporter/pkgs/container/monit_exporter)
+
+The following tags are available:
+
+- `x.y.z` pointing to the release with that version
+- `latest` pointing to the most recent released version
+- `master` pointing to the latest build from the default branch
+
+
+#### Scrape configuration
+
+The exporter will query the monit server every time it is scraped by prometheus. 
+If you want to reduce load on the monit server you need to change the scrape interval accordingly:
+
+```yml
+scrape_configs:
+  - job_name: 'monit'
+    scrape_interval: 90s
+    static_configs:
+      - targets: ['localhost:9338']
+```
+
 ### Update
 
 To rebuild the application with the latest Go release, execute the following commands:
@@ -68,30 +129,41 @@ sudo mv ~/go /usr/local/src
 echo 'PATH=$PATH:/usr/local/src/go/bin:$GOPATH/bin' | sudo tee /etc/profile.d/go.sh
 source /etc/profile.d/go.sh
 
-git clone https://github.com/liv-io/monit_exporter.git
+git clone https://github.com/monofox/monit_exporter.git
 cd ./monit_exporter/
 rm -f go\.mod  go\.sum
 sed -i 's@go-version: .*@go-version: ${GO_VERSION}@g' .github/workflows/release.yml
-go mod init github.com/liv-io/monit_exporter
+go mod init github.com/monofox/monit_exporter
 go mod tidy
 ```
 
 ## Usage
 
-The application will load the `config.toml` file located in the same directory if present. Use the `-conf` flag to override the default configuration file name and location.
+The application will load the `config.toml` file located in the same directory if present. 
+Use the `-conf` flag to override the default configuration file name and location.
 
 To run the application, simply execute the Go binary.
 
-### Parameters ###
-
-Parameter | Description | Type | Default
---- | --- | --- | ---
-`listen_address` | address and port to bind | String | localhost:9388
-`metrics_path` | relative path to expose metrics | String | /metrics
-`ignore_ssl` | whether of not to ignore ssl errors | Boolean | false
-`monit_scrape_uri` | uri to get monit status | String | http://localhost:2812/_status?format=xml&level=full
-`monit_user` | user for monit basic auth, if needed | String | none
-`monit_password` | password for monit status, if needed | String | none
+### Parameters
+
+Config parameter   | Environment equivalent   | Description                          | Type    | Default
+------------------ | ------------------------ | ------------------------------------ | ------- | ----------------------------------------------------
+`listen_address`   | `MONIT_LISTEN_ADDRESS`   | address and port to bind             | String  | 0.0.0.0:9388
+`metrics_path`     | `MONIT_METRICS_PATH`     | relative path to expose metrics      | String  | /metrics
+`ignore_ssl`       | `MONIT_IGNORE_SSL`       | whether of not to ignore ssl errors  | Boolean | false
+`monit_scrape_uri` | `MONIT_MONIT_SCRAPE_URI` | uri to get monit status              | String  | http://localhost:2812/_status?format=xml&level=full
+`monit_user`       | `MONIT_MONIT_USER`       | user for monit basic auth, if needed | String  | none
+`monit_password`   | `MONIT_MONIT_PASSWORD`   | password for monit status, if needed | String  | none
+
+### Example config
+```toml
+listen_address = "0.0.0.0:9388"
+metrics_path = "/metrics"
+ignore_ssl = false
+monit_scrape_uri = "https://localhost:2812/_status?format=xml&level=full"
+monit_user = "monit"
+monit_password = "example-secret"
+```
 
 ## License
 
@@ -101,23 +173,24 @@ See `LICENSE` file for more information.
 
 ## Contact
 
-Project: [monit_exporter](https://github.com/liv-io/monit_exporter)
+Project: [monit_exporter](https://github.com/monofox/monit_exporter)
 
 ## Credits
 
 Acknowledgements:
 * [commercetools](https://github.com/commercetools/monit_exporter)
 * [delucks](https://github.com/delucks/monit_exporter)
 * [chaordic](https://github.com/chaordic/monit_exporter)
+* [liv-io](https://github.com/liv-io/monit_exporter)
 
 <!-- shields.io -->
-[contributors-shield]: https://img.shields.io/github/contributors/liv-io/monit_exporter.svg?style=flat
-[contributors-url]: https://github.com/liv-io/monit_exporter/graphs/contributors
-[forks-shield]: https://img.shields.io/github/forks/liv-io/monit_exporter.svg?style=flat
-[forks-url]: https://github.com/liv-io/monit_exporter/network/members
-[stars-shield]: https://img.shields.io/github/stars/liv-io/monit_exporter.svg?style=flat
-[stars-url]: https://github.com/liv-io/monit_exporter/stargazers
-[issues-shield]: https://img.shields.io/github/issues/liv-io/monit_exporter.svg?style=flat
-[issues-url]: https://github.com/liv-io/monit_exporter/issues
-[license-shield]: https://img.shields.io/github/license/liv-io/monit_exporter.svg?style=flat
-[license-url]: https://github.com/liv-io/monit_exporter/blob/master/LICENSE
+[contributors-shield]: https://img.shields.io/github/contributors/monofox/monit_exporter.svg?style=flat
+[contributors-url]: https://github.com/monofox/monit_exporter/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/monofox/monit_exporter.svg?style=flat
+[forks-url]: https://github.com/monofox/monit_exporter/network/members
+[stars-shield]: https://img.shields.io/github/stars/monofox/monit_exporter.svg?style=flat
+[stars-url]: https://github.com/monofox/monit_exporter/stargazers
+[issues-shield]: https://img.shields.io/github/issues/monofox/monit_exporter.svg?style=flat
+[issues-url]: https://github.com/monofox/monit_exporter/issues
+[license-shield]: https://img.shields.io/github/license/monofox/monit_exporter.svg?style=flat
+[license-url]: https://github.com/monofox/monit_exporter/blob/master/LICENSE
diff --git a/monit_exporter.go b/monit_exporter.go
@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"strings"
 	"sync"
 
 	"github.com/prometheus/client_golang/prometheus"
@@ -31,8 +32,6 @@ const (
 	SERVICE_TYPE_NET        = 8
 )
 
-var configFile = flag.String("conf", "./config.toml", "Configuration file for exporter")
-
 var serviceTypes = map[int]string{
 	SERVICE_TYPE_FILESYSTEM: "filesystem",
 	SERVICE_TYPE_DIRECTORY:  "directory",
@@ -188,18 +187,24 @@ func ParseMonitStatus(data []byte) (monitXML, error) {
 
 // ParseConfig parse exporter binary options from command line
 func ParseConfig() *Config {
+	flag.String("conf", "./config.toml", "Configuration file for exporter")
 	flag.Parse()
 
 	v := viper.New()
 
+	// Provide all configurations as environment variable as well.
+	v.SetEnvPrefix(strings.ToUpper(namespace))
+	v.AutomaticEnv()
+
 	v.SetDefault("listen_address", "0.0.0.0:9388")
 	v.SetDefault("metrics_path", "/metrics")
 	v.SetDefault("ignore_ssl", false)
 	v.SetDefault("monit_scrape_uri", "http://localhost:2812/_status?format=xml&level=full")
 	v.SetDefault("monit_user", "")
 	v.SetDefault("monit_password", "")
-	v.SetConfigFile(*configFile)
+	v.SetConfigFile(flag.Lookup("conf").Value.String())
 	v.SetConfigType("toml")
+
 	err := v.ReadInConfig() // Find and read the config file
 	if err != nil {         // Handle errors reading the config file
 		log.Printf("Error reading config file: %s. Using defaults.", err)
@@ -339,7 +344,7 @@ func (e *Exporter) scrape() error {
 					e.checkMem.With(
 						prometheus.Labels{
 							"check_name": service.Name,
-							"type":       "kilobyteTotal",
+							"type":       "kilobyte_total",
 						}).Set(float64(service.Memory.KilobyteTotal * 1024))
 					e.checkCPU.With(
 						prometheus.Labels{