[307] Add support for histograms and distributions without unit conversion

[glightfoot]

This fixes #307 by moving millisecond-->second conversion to the buildEvent function for ms statTypes and also adds a case for h and d statTypes without the conversion. This effectively makes the TimerEvent value in seconds/unitless. Since this is no longer just limited to timers, should the TimerEvent be renamed to DistributionEvent or something similar?

Test cases were also added for the three distribution types and the conversions.

Summary:
ms units in milliseconds, converted to seconds for prometheus
h no units, no conversion
d no units, no conversion

The benchmark tests were broken, so the metrics were added back to them to get the benchmark working. That commit can be removed if necessary.
Before:

$ go test -bench=.
goos: darwin
goarch: amd64
pkg: github.com/prometheus/statsd_exporter
BenchmarkUDPListener1-12                   79335             12802 ns/op
BenchmarkUDPListener5-12                    3866            304820 ns/op
BenchmarkUDPListener50-12                     33          32112409 ns/op
BenchmarkExporterListener-12                 183           6583010 ns/op
PASS
ok      github.com/prometheus/statsd_exporter   5.714s

After:

$ go test -bench=.
goos: darwin
goarch: amd64
pkg: github.com/prometheus/statsd_exporter
BenchmarkUDPListener1-12                   80152             13512 ns/op
BenchmarkUDPListener5-12                    3638            331360 ns/op
BenchmarkUDPListener50-12                     31          34365441 ns/op
BenchmarkExporterListener-12                 183           6347688 ns/op
PASS
ok      github.com/prometheus/statsd_exporter   5.548s

These results show no significant increase in execution time, as the difference is within the variation observed on repeated benchmarking.

[glightfoot]

@matthiasr

[matthiasr]

This looks great! Thank you for fixing the benchmarks.

You are right, we should rename the event. In line with the client library naming I would like to call it an ObserverEvent, does that sound right?

[glightfoot]

ObserverEvent makes sense and is nice and consistent. I pushed up that change now. The only thing I can think of now is that there are plenty of stats calls that still reference timer event:

b.EventStats.WithLabelValues("timer").Inc()

I think it makes sense to change those to "observer", but that would be another breaking change to metrics usage, so let me know what you'd like to see.

[glightfoot]

The other thing I can see is there are still lots of references to Timer in the Mapper pkg. I can change them, but then that breaks the configs since things like timer_type in the defaults would become observer_type, which would need some explaining in the documentation

[matthiasr]

Ah, you ask all the good questions. I'm fine with "breaking" the metrics, a note in the changelog will help, which I will add anyway.

I am less willing to break configurations, how hard would it be to change the primary option but maintain compatibility? (i.e. document observer_type, deprecate timer_type but treat them the same)?

[glightfoot]

Ok I'll change the metrics now. I haven't looked too much at the mapper config code, so I am not sure how simple of a change that will be

[glightfoot]

I added some custom unmarshalers to handle both keys. observer_type will always override timer_type. Let me know what you think about this approach. Also note that while this passes all test right now, I haven't yet compiled it and run a full test

[glightfoot]

I built this branch and tested with the following:

testing unit conversion and deprecated config value

$ cat << EOF > test-config.yaml
defaults:
  timer_type: histogram
  buckets: [ 0.1, 0.5, 1 ]
mappings:
- match: "(.*)"
  name: '\$1'
  match_type: regex
EOF

$ ./statsd_exporter --statsd.mapping-config=test-config.yaml &

$ for x in `seq 1 10`; do
    echo "foo_ms:200|ms" | nc -w 1 -cu localhost 9125
    echo "foo_h:200|h" | nc -w 1 -cu localhost 9125
    echo "foo_d:200|d" | nc -w 1 -cu localhost 9125
done

$ curl -s localhost:9102/metrics | grep -E "foo|statsd_exporter_events_total"
# HELP foo_d Metric autogenerated by statsd_exporter.
# TYPE foo_d histogram
foo_d_bucket{le="0.1"} 0
foo_d_bucket{le="0.5"} 0
foo_d_bucket{le="1"} 0
foo_d_bucket{le="+Inf"} 10
foo_d_sum 2000
foo_d_count 10
# HELP foo_h Metric autogenerated by statsd_exporter.
# TYPE foo_h histogram
foo_h_bucket{le="0.1"} 0
foo_h_bucket{le="0.5"} 0
foo_h_bucket{le="1"} 0
foo_h_bucket{le="+Inf"} 10
foo_h_sum 2000
foo_h_count 10
# HELP foo_ms Metric autogenerated by statsd_exporter.
# TYPE foo_ms histogram
foo_ms_bucket{le="0.1"} 0
foo_ms_bucket{le="0.5"} 10
foo_ms_bucket{le="1"} 10
foo_ms_bucket{le="+Inf"} 10
foo_ms_sum 1.9999999999999998
foo_ms_count 10
# HELP statsd_exporter_events_total The total number of StatsD events seen.
# TYPE statsd_exporter_events_total counter
statsd_exporter_events_total{type="observer"} 30

testing new config overriding deprecated timer_type

$ cat << EOF > test-config.yaml
defaults:
  observer_type: histogram
  # the deprecated timer_type is overridden by observer_type
  timer_type: summary
  buckets: [ 0.1, 0.5, 1 ]
mappings:
- match: "(.*)"
  name: '\$1'
  match_type: regex
EOF

$ ./statsd_exporter --statsd.mapping-config=test-config.yaml &

$ for x in `seq 1 10`; do
    echo "foo_ms:200|ms" | nc -w 1 -cu localhost 9125
    echo "foo_h:200|h" | nc -w 1 -cu localhost 9125
    echo "foo_d:200|d" | nc -w 1 -cu localhost 9125
done

$ curl -s localhost:9102/metrics | grep -E "foo|statsd_exporter_events_total"
# HELP foo_d Metric autogenerated by statsd_exporter.
# TYPE foo_d histogram
foo_d_bucket{le="0.1"} 0
foo_d_bucket{le="0.5"} 0
foo_d_bucket{le="1"} 0
foo_d_bucket{le="+Inf"} 10
foo_d_sum 2000
foo_d_count 10
# HELP foo_h Metric autogenerated by statsd_exporter.
# TYPE foo_h histogram
foo_h_bucket{le="0.1"} 0
foo_h_bucket{le="0.5"} 0
foo_h_bucket{le="1"} 0
foo_h_bucket{le="+Inf"} 10
foo_h_sum 2000
foo_h_count 10
# HELP foo_ms Metric autogenerated by statsd_exporter.
# TYPE foo_ms histogram
foo_ms_bucket{le="0.1"} 0
foo_ms_bucket{le="0.5"} 10
foo_ms_bucket{le="1"} 10
foo_ms_bucket{le="+Inf"} 10
foo_ms_sum 1.9999999999999998
foo_ms_count 10
# HELP statsd_exporter_events_total The total number of StatsD events seen.
# TYPE statsd_exporter_events_total counter
statsd_exporter_events_total{type="observer"} 30

Is there anything else necessary for this PR?

[matthiasr]

This is awesome, thank you!