diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c6176a1..6c90071 100644 --- a/.github/workflows/release.yml +++ b/.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 diff --git a/README.md b/README.md index 970dea0..ac1b435 100644 --- a/README.md +++ b/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 \ No newline at end of file +[values.yaml]: https://github.com/czerwonk/ping_exporter/blob/master/dist/charts/ping-exporter/values.yaml diff --git a/collector.go b/collector.go index ab8e476..2442170 100644 --- a/collector.go +++ b/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{} ) diff --git a/main.go b/main.go index 6a26252..5b9e543 100644 --- a/main.go +++ b/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() {