Merge branch 'foogod-version1'

.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
     name: Create Release
     runs-on: ubuntu-latest
     env:
-      GO_VERSION: "1.16"
+      GO_VERSION: "1.17"
     steps:
       - name: Checkout code
         uses: actions/checkout@v2

README.md

@@ -52,11 +52,11 @@ $ ./ping_exporter --dns.nameserver=1.1.1.1:53 [other options]
 
 ### Exported metrics
 
-- `ping_rtt_best_ms`:          Best round trip time in millis
-- `ping_rtt_worst_ms`:         Worst round trip time in millis
-- `ping_rtt_mean_ms`:          Mean round trip time in millis
-- `ping_rtt_std_deviation_ms`: Standard deviation in millis
-- `ping_loss_percent`:         Packet loss in percent
+- `ping_rtt_best_seconds`:          Best round trip time in seconds
+- `ping_rtt_worst_seconds`:         Worst round trip time in seconds
+- `ping_rtt_mean_seconds`:          Mean round trip time in seconds
+- `ping_rtt_std_deviation_seconds`: Standard deviation in seconds
+- `ping_loss_ratio`:                Packet loss as a value from 0.0 to 1.0
 
 Each metric has labels `ip` (the target's IP address), `ip_version`
 (4 or 6, corresponding to the IP version), and `target` (the target's
@@ -65,57 +65,6 @@ name).
 Additionally, a `ping_up` metric reports whether the exporter
 is running (and in which version).
 
-#### Different time unit
-
-The `*_ms` metrics actually violate the recommendations by
-[Prometheus](https://prometheus.io/docs/practices/naming/#base-units),
-whereby time values should be expressed in seconds (not milliseconds).
-
-To accomodate for this, we've added a command line switch to select
-the proper scale:
-
-```console
-$ # keep using millis
-$ ./ping_exporter --metrics.rttunit=ms [other options]
-$ # use seconds instead
-$ ./ping_exporter --metrics.rttunit=s [other options]
-$ # use both millis and seconds
-$ ./ping_exporter --metrics.rttunit=both [other options]
-```
-
-For the foreseeable future, the default is `--metrics.rttunit=ms`.
-
-If you used the `ping_exporter` in the past, and want to migrate, start
-using `--metrics.rttunit=both` now. This gives you the opportunity to
-update all your alerts, dashboards, and other software depending on ms
-values to use proper scale (you "just" need to apply a factor of 1000
-on everything). When you're ready, you just need to switch to
-`--metrics.rttunit=s`.
-
-#### Deprecated metrics
-
-- `ping_rtt_ms`: Round trip trim in millis
-
-This metric has a label `type` with one of the following values:
-
-- `best` denotes best round trip time
-- `worst` denotes worst round trip time
-- `mean` denotes mean round trip time
-- `std_dev` denotes standard deviation
-
-These metrics are exported by default, but this may change with a future
-release of this exporter.
-
-To ensure forward- or backward compatability, use the `--metrics.deprecated`
-flag:
-
-```console
-$ # also export deprecated metrics
-$ ./ping_exporter --metrics.deprecated=enable [other options]
-$ # or omit deprecated metrics
-$ ./ping_exporter --metrics.deprecated=disable [other options]
-```
-
 ### Shell
 
 To run the exporter:
@@ -151,6 +100,14 @@ On Linux systems `CAP_NET_RAW` is required to run `ping_exporter` as unprivilige
 
 When run through a rootless Docker implementation on Linux, the flag `--cap-add=CAP_NET_RAW` should be added to the `docker run` invocation.
 
+If being invoked via systemd, you can alternately just add the following
+settings to the service's unit file in the `[Service]` section:
+
+```console
+CapabilityBoundingSet=CAP_NET_RAW
+AmbientCapabilities=CAP_NET_RAW
+```
+
 ## Docker
 
 https://hub.docker.com/r/czerwonk/ping_exporter
@@ -218,6 +175,85 @@ NAME: ping-exporter
 | tolerations | list | `[]` | [Tolerations] | 
 
 
+## Changes from previous versions
+
+### `ping_loss_ratio` vs `ping_loss_percent`
+
+Previous versions of the exporter reported packet loss via a metric named
+`ping_loss_percent`.  This was somewhat misleading / wrong, because it never
+actually reported a percent value (it was always a value between 0 and 1).  To
+make this more clear, and to match with [Prometheus best
+practices](https://prometheus.io/docs/practices/naming/#base-units), this
+metric has been renamed to `ping_loss_ratio` instead.
+
+If you had already been using an earlier version and want to continue to record
+this metric in Prometheus using the old name, this can be done using the
+`metric_relabel_configs` options in the Prometheus config, like so:
+
+```console
+- job_name: "ping"
+  static_configs:
+    <...>
+  metric_relabel_configs:
+    - source_labels: [__name__]
+      regex: "ping_loss_ratio"
+      target_label: __name__
+      replacement: "ping_loss_percent"
+```
+
+### Time units
+
+As per the recommendations for [Prometheus best
+practices](https://prometheus.io/docs/practices/naming/#base-units), the
+exporter reports time values in seconds by default.  Previous versions
+defaulted to reporting milliseconds by default (with metric names ending in
+`_ms` instead of `_seconds`), so if you are upgrading from an older version,
+this may require some adjustment.
+
+It is possible to change the ping exporter to report times in milliseconds
+instead (this is not recommended, but may be useful for compatibility with
+older versions, etc).  To do this, the `metrics.rttunit` command-line switch
+can be used:
+
+```console
+$ # keep using seconds (default)
+$ ./ping_exporter --metrics.rttunit=s [other options]
+$ # use milliseconds instead
+$ ./ping_exporter --metrics.rttunit=ms [other options]
+$ # report both millis and seconds
+$ ./ping_exporter --metrics.rttunit=both [other options]
+```
+
+If you used the `ping_exporter` in the past, and want to migrate, start
+using `--metrics.rttunit=both` now. This gives you the opportunity to
+update all your alerts, dashboards, and other software depending on ms
+values to use proper scale (you "just" need to apply a factor of 1000
+on everything). When you're ready, you just need to switch to
+`--metrics.rttunit=s` (or just remove the command-line option entirely).
+
+### Deprecated metrics
+
+Previous versions of this exporter provided an older form of the RTT metrics
+as:
+
+- `ping_rtt_ms`: Round trip times in millis
+
+This metric had a label `type` with one of the following values:
+
+- `best` denotes best round trip time
+- `worst` denotes worst round trip time
+- `mean` denotes mean round trip time
+- `std_dev` denotes standard deviation
+
+These metrics are no longer exported by default, but can be enabled for
+backwards compatibility using the `--metrics.deprecated` command-line flag:
+
+```console
+$ # also export deprecated metrics
+$ ./ping_exporter --metrics.deprecated=enable [other options]
+$ # or omit deprecated metrics (default)
+$ ./ping_exporter --metrics.deprecated=disable [other options]
+```
 
 ## Contribute
 
@@ -235,4 +271,4 @@ Daniel Czerwonk [dan_nrw](https://twitter.com/dan_nrw)
 [Affinity]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
 [command-line arguments]: https://github.com/czerwonk/ping_exporter#different-time-unit
 [config file]: https://github.com/czerwonk/ping_exporter#config-file
-[values.yaml]: https://github.com/czerwonk/ping_exporter/blob/master/dist/charts/ping-exporter/values.yaml
+[values.yaml]: https://github.com/czerwonk/ping_exporter/blob/master/dist/charts/ping-exporter/values.yaml

collector.go

@@ -19,7 +19,7 @@ var (
 	worstDesc  = newScaledDesc("rtt_worst", "Worst round trip time", labelNames)
 	meanDesc   = newScaledDesc("rtt_mean", "Mean round trip time", labelNames)
 	stddevDesc = newScaledDesc("rtt_std_deviation", "Standard deviation", labelNames)
-	lossDesc   = newDesc("loss_percent", "Packet loss in percent", labelNames, nil)
+	lossDesc   = newDesc("loss_ratio", "Packet loss from 0.0 to 1.0", labelNames, nil)
 	progDesc   = newDesc("up", "ping_exporter version", nil, prometheus.Labels{"version": version})
 	mutex      = &sync.Mutex{}
 )

main.go

@@ -19,7 +19,7 @@ import (
 	"gopkg.in/alecthomas/kingpin.v2"
 )
 
-const version string = "0.4.8"
+const version string = "1.0.0"
 
 var (
 	showVersion   = kingpin.Flag("version", "Print version information").Default().Bool()
@@ -39,10 +39,10 @@ var (
 
 var (
 	enableDeprecatedMetrics = true // default may change in future
-	deprecatedMetrics       = kingpin.Flag("metrics.deprecated", "Enable or disable deprecated metrics (`ping_rtt_ms{type=best|worst|mean|std_dev}`). Valid choices: [enable, disable]").Default("enable").String()
+	deprecatedMetrics       = kingpin.Flag("metrics.deprecated", "Enable or disable deprecated metrics (`ping_rtt_ms{type=best|worst|mean|std_dev}`). Valid choices: [enable, disable]").Default("disable").String()
 
 	rttMetricsScale = rttInMills // might change in future
-	rttMode         = kingpin.Flag("metrics.rttunit", "Export ping results as either millis (default), or seconds (best practice), or both (for migrations). Valid choices: [ms, s, both]").Default("ms").String()
+	rttMode         = kingpin.Flag("metrics.rttunit", "Export ping results as either seconds (default), or milliseconds (deprecated), or both (for migrations). Valid choices: [s, ms, both]").Default("s").String()
 )
 
 func main() {