mirrors/statsd_exporter
1
0
Fork 1
mirror of https://github.com/prometheus/statsd_exporter.git synced 2024-12-01 11:41:01 +00:00
Code Issues Projects Releases Packages Wiki Activity

Changelog and documentation update for #314

Browse source 
Update the README to reflect #314. Add an entry to the changelog
with extended compatibility notes.

Signed-off-by: Matthias Rampke <matthias@prometheus.io>
This commit is contained in:
Matthias Rampke 2020-06-19 11:56:55 +00:00
parent 7ba3550f8f
commit b64e07c7d9
No known key found for this signature in database
GPG key ID: F9AFF7F67ACE10BA
2 changed files with 42 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
CHANGELOG.md
View file

@ -1,6 +1,17 @@
## 0.17.0 / unreleased ## 0.17.0 / unreleased
* [FEATURE] Offline configuration check ([#312](https://github.com/prometheus/statsd_exporter/pull/312)) * [FEATURE] Offline configuration check ([#312](https://github.com/prometheus/statsd_exporter/pull/312))
* [CHANGE] Support non-timer distributions without unit conversion ([#314](https://github.com/prometheus/statsd_exporter/pull/314))
Distribution and histogram events (type `d`, `h`) are now treated as distinct from timer events (type `ms`).
Their values are observed as they are, while timer events are converted from milliseconds to seconds.
To reflect this generalization, the `observer_type` mapping option replaces `timer_type`.
Similary, change `match_metric_type: timer` to `match_metric_type: observer`.
The old name remains available for compatibility.
For users of the mapper library, the `ObserverEvent` replaces `TimerEvent`.
For timer metrics, it is emitted by the mapper already converted to seconds.
## 0.16.0 / 2020-05-29 ## 0.16.0 / 2020-05-29

65
README.md
View file

@ -162,9 +162,7 @@ In general, the different metric types are translated as follows:
StatsD counter -> Prometheus counter StatsD counter -> Prometheus counter
StatsD timer -> Prometheus summary <-- indicates timer quantiles StatsD timer, histogram, distribution -> Prometheus summary or histogram
-> Prometheus counter (suffix `_total`) <-- indicates total time spent
-> Prometheus counter (suffix `_count`) <-- indicates total number of timer events
An example mapping configuration: An example mapping configuration:
@ -246,17 +244,18 @@ mappings:
code: "$1" code: "$1"
``` ```
### StatsD timers ### StatsD timers and distributions
By default, statsd timers are represented as a Prometheus summary with By default, statsd timers and distributions (collectively "observers") are
quantiles. You may optionally configure the [quantiles and acceptable represented as a Prometheus summary with quantiles. You may optionally
error](https://prometheus.io/docs/practices/histograms/#quantiles), as configure the [quantiles and acceptable
well as adjusting how the summary metric is aggregated: error](https://prometheus.io/docs/practices/histograms/#quantiles), as well
as adjusting how the summary metric is aggregated:
```yaml ```yaml
mappings: mappings:
- match: "test.timing.*.*.*" - match: "test.timing.*.*.*"
timer_type: summary observer_type: summary
name: "my_timer" name: "my_timer"
labels: labels:
provider: "$2" provider: "$2"
@ -280,19 +279,17 @@ mappings:
The default quantiles are 0.99, 0.9, and 0.5. The default quantiles are 0.99, 0.9, and 0.5.
The default summary age is 10 minutes, the default number of buckets The default summary age is 10 minutes, the default number of buckets
is 5 and the default buffer size is 500. See also the is 5 and the default buffer size is 500.
[`golang_client` docs](https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts). See also the [`golang_client` docs](https://godoc.org/github.com/prometheus/client_golang/prometheus#SummaryOpts).
The `max_summary_age` corresponds to `SummaryOptions.MaxAge`, `summary_age_buckets` The `max_summary_age` corresponds to `SummaryOptions.MaxAge`, `summary_age_buckets` to `SummaryOptions.AgeBuckets` and `stream_buffer_size` to `SummaryOptions.BufCap`.
to `SummaryOptions.AgeBuckets` and `stream_buffer_size` to `SummaryOptions.BufCap`.
In the configuration, one may also set the timer type to "histogram". The In the configuration, one may also set the observer type to "histogram". For example,
default is "summary" as in the plain text configuration format. For example, to set the observer type for a single timer metric:
to set the timer type for a single metric:
```yaml ```yaml
mappings: mappings:
- match: "test.timing.*.*.*" - match: "test.timing.*.*.*"
timer_type: histogram observer_type: histogram
histogram_options: histogram_options:
buckets: [ 0.01, 0.025, 0.05, 0.1 ] buckets: [ 0.01, 0.025, 0.05, 0.1 ]
name: "my_timer" name: "my_timer"
@ -302,18 +299,18 @@ mappings:
job: "${1}_server" job: "${1}_server"
``` ```
Note that timers will be accepted with the `ms`, `h`, and `d` statsd types. The first two are timers and histograms and the `d` type is for DataDog's "distribution" type. The distribution type is treated identically to timers and histograms. Timers will be accepted with the `ms` statsd type.
Statsd timer data is transmitted in milliseconds, while Prometheus expects the unit to be seconds.
The exporter converts all timer observations to seconds.
It should be noted that whereas timers in statsd expects the unit of timing data to be in milliseconds, Histogram and distribution events (`h` and `d` metric type) are not subject to unit conversion.
prometheus expects the unit to be seconds. Hence, the exporter converts all timers to seconds
before exporting them.
### DogStatsD Client Behavior ### DogStatsD Client Behavior
#### `timed()` decorator #### `timed()` decorator
If you are using the DogStatsD client's [timed](https://datadogpy.readthedocs.io/en/latest/#datadog.threadstats.base.ThreadStats.timed) decorator, The DogStatsD client's [timed](https://datadogpy.readthedocs.io/en/latest/#datadog.threadstats.base.ThreadStats.timed) decorator emits the metric in seconds but uses the `ms` type.
it emits the metric in seconds, set [use_ms](https://datadogpy.readthedocs.io/en/latest/index.html?highlight=use_ms) to `True` to fix this. Set [`use_ms=True`](https://datadogpy.readthedocs.io/en/latest/index.html?highlight=use_ms) to send the correct units.
### Regular expression matching ### Regular expression matching
@ -339,20 +336,20 @@ Note, that one may also set the histogram buckets. If not set, then the default
[Prometheus client values](https://godoc.org/github.com/prometheus/client_golang/prometheus#pkg-variables) are used: `[.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]`. `+Inf` is added [Prometheus client values](https://godoc.org/github.com/prometheus/client_golang/prometheus#pkg-variables) are used: `[.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]`. `+Inf` is added
automatically. automatically.
`timer_type` is only used when the statsd metric type is a timer. `buckets` is `observer_type` is only used when the statsd metric type is a timer, histogram, or distribution.
only used when the statsd metric type is a timerand the `timer_type` is set to `buckets` is only used when the statsd metric type is one of these, and the `observer_type` is set to `histogram`.
"histogram."
### Global defaults ### Global defaults
One may also set defaults for the timer type, buckets or quantiles, and match_type. These will be used One may also set defaults for the observer type, buckets or quantiles, and match type.
by all mappings that do not define these. These will be used by all mappings that do not define them.
An option that can only be configured in `defaults` is `glob_disable_ordering`, which is `false` if omitted. By setting this to `true`, `glob` match type will not honor the occurance of rules in the mapping rules file and always treat `*` as lower priority than a general string. An option that can only be configured in `defaults` is `glob_disable_ordering`, which is `false` if omitted.
By setting this to `true`, `glob` match type will not honor the occurance of rules in the mapping rules file and always treat `*` as lower priority than a concrete string.
```yaml ```yaml
defaults: defaults:
timer_type: histogram observer_type: histogram
buckets: [.005, .01, .025, .05, .1, .25, .5, 1, 2.5 ] buckets: [.005, .01, .025, .05, .1, .25, .5, 1, 2.5 ]
match_type: glob match_type: glob
glob_disable_ordering: false glob_disable_ordering: false
@ -366,9 +363,9 @@ mappings:
outcome: "$3" outcome: "$3"
job: "${1}_server" job: "${1}_server"
# This will be a summary timer. # This will be a summary timer.
- match: "other.timing.*.*.*" - match: "other.distribution.*.*.*"
timer_type: summary observer_type: summary
name: "other_timer" name: "other_distribution"
labels: labels:
provider: "$2" provider: "$2"
outcome: "$3" outcome: "$3"
@ -437,7 +434,7 @@ mappings:
provider: "$1" provider: "$1"
``` ```
Possible values for `match_metric_type` are `gauge`, `counter` and `timer`. Possible values for `match_metric_type` are `gauge`, `counter` and `observer`.
### Mapping cache size and cache replacement policy ### Mapping cache size and cache replacement policy