(TK-354) Add examples to metrics docs
And some other tweaks in response to review.
This commit is contained in:
parent
81659166cf
commit
c6b6b91da8
2 changed files with 148 additions and 8 deletions
|
@ -94,7 +94,7 @@ which is a map containing options for the HTTP request. These options are as fol
|
|||
* `:unbuffered-stream` which is a variant of `:stream` that will buffer as little data as possible
|
||||
* `:query-params`: optional; used to set the query parameters of an http request. This should be
|
||||
a map, where each key and each value is a String.
|
||||
* `:metric-id`: optional; a vector of keywords. A metric will be created for
|
||||
* `:metric-id`: optional; a vector of keywords or strings. A metric will be created for
|
||||
each element in the vector, with each appending to the previous.
|
||||
|
||||
For example, say you want to make a GET request with
|
||||
|
|
154
doc/metrics.md
154
doc/metrics.md
|
@ -3,9 +3,11 @@
|
|||
Both the Java client and the Clojure client have [Dropwizard
|
||||
Metrics](http://metrics.dropwizard.io/3.1.0/) support - they both accept as an
|
||||
option a `MetricRegistry` to which they will register http metrics for each
|
||||
request, as well as metrics for an metric-ids specified in the request options.
|
||||
request, as well as metrics for an metric-ids specified in the request
|
||||
options. This support is experimental - names of metrics and the exact API may
|
||||
change.
|
||||
|
||||
For using metrics with either the Java client and the Clojure client you must
|
||||
For using metrics with either the Java client or the Clojure client you must
|
||||
already have created a Dropwizard `MetricRegistry`.
|
||||
|
||||
- [Metrics prefix](#metrics-prefix)
|
||||
|
@ -213,6 +215,20 @@ of the options map:
|
|||
|
||||
(the same works with the `sync` client).
|
||||
|
||||
In [Trapperkeeper](https://github.com/puppetlabs/trapperkeeper) applications,
|
||||
creating and managing a `MetricRegistry` can be done easily with
|
||||
[trapperkeeper-metrics](https://github.com/puppetlabs/trapperkeeper-metrics):
|
||||
|
||||
```clojure
|
||||
(defservice my-trapperkeeper-service
|
||||
MyService
|
||||
[[:MetricsService get-metrics-registry]]
|
||||
(init [this context]
|
||||
(let [registry (get-metrics-registry)
|
||||
client (async/create-client {:metric-registry registry})]
|
||||
...)))
|
||||
```
|
||||
|
||||
Any client that is created with a `MetricRegistry` will automatically have
|
||||
`url` and `url-and-method` metrics registered.
|
||||
|
||||
|
@ -245,13 +261,74 @@ To get all `Timer` objects registered for a `MetricRegistry`, use the
|
|||
`MetricRegistry` as an argument and returns a map with three keys: `:url`
|
||||
`:url-and-method`, and `:metric-id`. Under each of these keys is a sequence of
|
||||
`Timer` objects of the corresponding type. If there are no timers of a certain
|
||||
type, the sequence will be empty.
|
||||
type, the sequence will be empty. The output of this function conforms to the
|
||||
`common/AllTimers` schema.
|
||||
|
||||
Example:
|
||||
|
||||
```clojure
|
||||
(common/get client "http://test.com" {:metric-id [:foo :bar :baz]})
|
||||
...
|
||||
(metrics/get-client-metrics metric-registry)
|
||||
=>
|
||||
{:url [#object[com.puppetlabs.http.client.metrics.UrlClientTimer
|
||||
0x66cf1f05
|
||||
"com.puppetlabs.http.client.metrics.UrlClientTimer@66cf1f05"]]
|
||||
:url-and-method [#object[com.puppetlabs.http.client.metrics.UrlAndMethodClientTimer
|
||||
0x6fe5444c
|
||||
"com.puppetlabs.http.client.metrics.UrlAndMethodClientTimer@6fe5444c"]]
|
||||
:metric-id [#object[com.puppetlabs.http.client.metrics.MetricIdClientTimer
|
||||
0x690c10c5
|
||||
"com.puppetlabs.http.client.metrics.MetricIdClientTimer@690c10c5"]
|
||||
#object[com.puppetlabs.http.client.metrics.MetricIdClientTimer
|
||||
0xb7aca2e
|
||||
"com.puppetlabs.http.client.metrics.MetricIdClientTimer@b7aca2e"]
|
||||
#object[com.puppetlabs.http.client.metrics.MetricIdClientTimer
|
||||
0x4ef82829
|
||||
"com.puppetlabs.http.client.metrics.MetricIdClientTimer@4ef82829"]]}
|
||||
```
|
||||
|
||||
To get metric data for all `Timer`s registered on a `MetricRegistry`, use the
|
||||
`get-client-metrics-data` function. This takes the `MetricRegistry` and
|
||||
returns a map with `:url`, `:url-and-method`, and `:metric-id` as keys. Under
|
||||
each of these keys is a sequence of maps, each map containing metrics data
|
||||
(see [Getting back metrics](#Getting-back-metrics) above.
|
||||
`get-client-metrics-data` function. This takes the `MetricRegistry` and returns
|
||||
a map with `:url`, `:url-and-method`, and `:metric-id` as keys. Under each of
|
||||
these keys is a sequence of maps, each map containing metrics data (see
|
||||
[Getting back metrics](#Getting-back-metrics) above, conforming to the
|
||||
`common/AllMetricsData` schema.
|
||||
|
||||
Example:
|
||||
|
||||
```clojure
|
||||
(common/get client "http://test.com" {:metric-id [:foo :bar :baz]})
|
||||
...
|
||||
(metrics/get-client-metrics-data metric-registry)
|
||||
=>
|
||||
{:url ({:count 1
|
||||
:mean 553
|
||||
:aggregate 553
|
||||
:metric-name "puppetlabs.http-client.experimental.with-url.http://test.com.full-response"
|
||||
:url "http://test.com"})
|
||||
:url-and-method ({:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-url-and-method.http://test.com.GET.full-response"
|
||||
:url "http://test.com"
|
||||
:method "GET"})
|
||||
:metric-id ({:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-metric-id.foo.bar.baz.full-response"
|
||||
:metric-id ["foo" "bar" "baz"]}
|
||||
{:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-metric-id.foo.bar.full-response"
|
||||
:metric-id ["foo" "bar"]}
|
||||
{:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-metric-id.foo.full-response"
|
||||
:metric-id ["foo"]})}
|
||||
```
|
||||
|
||||
#### Filtering by URL
|
||||
|
||||
|
@ -262,6 +339,23 @@ Both of these take as arguments the `MetricRegistry` and a string url. If no
|
|||
url is provided, return all url metrics/metrics data in a sequence. If no
|
||||
metrics are registered for that url, return an empty sequence.
|
||||
|
||||
Example:
|
||||
|
||||
```clojure
|
||||
(common/get client "http://test.com" {:metric-id [:foo :bar :baz]})
|
||||
...
|
||||
(metrics/get-client-metrics-data-by-url metric-registry "http://test.com")
|
||||
=>
|
||||
({:count 1
|
||||
:mean 553
|
||||
:aggregate 553
|
||||
:metric-name "puppetlabs.http-client.experimental.with-url.http://test.com.full-response"
|
||||
:url "http://test.com"})
|
||||
|
||||
(metrics/get-client-metrics-data-by-url metric-registry "http://not-a-matching-url.com")
|
||||
=> ()
|
||||
```
|
||||
|
||||
#### Filtering by URL and method
|
||||
|
||||
To get URL and method metrics and metrics data, use the
|
||||
|
@ -274,6 +368,26 @@ keyword HTTP method. If no url and method is provided, return all url
|
|||
metrics/metrics data in a sequence. If no metrics are registered for that url
|
||||
and method, return an empty sequence.
|
||||
|
||||
Example:
|
||||
|
||||
```clojure
|
||||
(common/get client "http://test.com" {:metric-id [:foo :bar :baz]})
|
||||
...
|
||||
(metrics/get-client-metrics-data-by-url-and-method metric-registry "http://test.com" :get)
|
||||
=>
|
||||
({:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-url-and-method.http://test.com.GET.full-response"
|
||||
:url "http://test.com"
|
||||
:method "GET"})
|
||||
|
||||
:method "GET"})
|
||||
|
||||
(metrics/get-client-metrics-data-by-url-and-method metric-registry "http://test.com" :post)
|
||||
=> ()
|
||||
```
|
||||
|
||||
#### Filtering by metric-id
|
||||
|
||||
To get metric-id metrics and metrics data, use the
|
||||
|
@ -284,3 +398,29 @@ Both of these take as arguments the `MetricRegistry` and a metric-id - as a
|
|||
vector of keywords or strings (if special characters are needed, use strings).
|
||||
If no metric-id is provided, will return all metric-id metrics. If no metrics
|
||||
are registered for that metric-id, returns an empty list.
|
||||
|
||||
Example:
|
||||
|
||||
```clojure
|
||||
(common/get client "http://test.com" {:metric-id [:foo :bar :baz]})
|
||||
...
|
||||
(metrics/get-client-metrics-data-by-metric-id metric-registry [:foo])
|
||||
=>
|
||||
({:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-metric-id.foo.full-response"
|
||||
:metric-id ["foo"]})
|
||||
|
||||
(metrics/get-client-metrics-data-by-metric-id metric-registry [:foo :bar])
|
||||
=>
|
||||
({:count 1
|
||||
:mean 554
|
||||
:aggregate 554
|
||||
:metric-name "puppetlabs.http-client.experimental.with-metric-id.foo.bar.full-response"
|
||||
:metric-id ["foo" "bar"]})
|
||||
|
||||
(metrics/get-client-metrics-data-by-metric-id metric-registry [:foo :nope])
|
||||
=> ()
|
||||
```
|
||||
|
||||
|
|
Loading…
Reference in a new issue