283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
|
# Metrics
|
||
|
|
||
|
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.
|
||
|
|
||
|
For using metrics with either the Java client and the Clojure client you must
|
||
|
already have created a Dropwizard `MetricRegistry`.
|
||
|
|
||
|
- [Metrics prefix](#metrics-prefix)
|
||
|
- [Types of metrics](#types-of-metrics)
|
||
|
- [Getting back metrics](#getting-back-metrics)
|
||
|
- [Java API](#java-api)
|
||
|
- [Creating a client with metrics](#creating-a-client-with-metrics)
|
||
|
- [Setting a metric-id](#setting-a-metric-id)
|
||
|
- [Filtering metrics](#filtering-metrics)
|
||
|
- [Filtering by URL](#filtering-by-url)
|
||
|
- [Filtering by URL and method](#filtering-by-url-and-method)
|
||
|
- [Filtering by metric-id](#filtering-by-metric-id)
|
||
|
- [Clojure API](#clojure-api)
|
||
|
- [Creating a client with metrics](#creating-a-client-with-metrics-1)
|
||
|
- [Setting a metric-id](#setting-a-metric-id-1)
|
||
|
- [Filtering metrics](#filtering-metrics-1)
|
||
|
- [Filtering by URL](#filtering-by-url-1)
|
||
|
- [Filtering by URL and method](#filtering-by-url-and-method-1)
|
||
|
- [Filtering by metric-id](#filtering-by-metric-id-1)
|
||
|
|
||
|
|
||
|
## Metrics prefix
|
||
|
|
||
|
All http metrics are prefixed with `puppetlabs.http-client.experimental`.
|
||
|
|
||
|
## Types of metrics
|
||
|
|
||
|
There are two types of metrics: *full response* and *initial response*. Full
|
||
|
response metrics stop when all bytes of the response have been read by the
|
||
|
client. Initial response metrics stop when the first byte of the response has
|
||
|
been received by the client. Full response metrics are suffixed with
|
||
|
`full-response`. Initial response metric support has not yet been
|
||
|
implementedare suffixed with `full-response`. Initial response metric support
|
||
|
has not yet been implemented.
|
||
|
|
||
|
There are three categories of metrics: `url` metrics, `url-and-method`
|
||
|
metrics, and `metric-id` metrics. `url` and `url-and-method` metrics are
|
||
|
created automatically for each request; `metric-id` metrics are only created
|
||
|
for requests that have a `metric-id` request option specified.
|
||
|
|
||
|
Each http request will have a metric name created for its url (stripped of
|
||
|
query strings and url fragments), as well as for the url + method name. `url`
|
||
|
metrics have `with-url` after the prefix, followed by the url.
|
||
|
`url-and-method` metrics have `with-url-and-method` after the prefix, followed
|
||
|
by the url and then the capitalized HTTP method.
|
||
|
|
||
|
So, for example, a `GET` request to `http://foobar.com` would create a metric
|
||
|
`puppetlabs.http-client.experimental.with-url.http://foobar.com.full-response`
|
||
|
and a metric
|
||
|
`puppetlabs.http-client.experimental.with-url-and-method.http://foobar.com.GET.full-response`.
|
||
|
|
||
|
It is also possible to give a request a `metric-id`. The `metric-id` is an
|
||
|
array of strings (Java) or keywords (Clojure). For each element in the array,
|
||
|
a metric name will be created, appending to the previous elements. `metric-id`
|
||
|
metrics have `with-metric-id` after the metric prefix, followed by the
|
||
|
metric-id.
|
||
|
|
||
|
So, for example, for a metric-id `["foo", "bar", "baz"]`, the metrics
|
||
|
`puppetlabs.http-client.experimental.with-metric-id.foo.full-response`,
|
||
|
`puppetlabs.http-client.experimental.with-metric-id.foo.bar.full-response`,
|
||
|
and
|
||
|
`puppetlabs.http-client.experimental.with-metric-id.foo.bar.baz.full-response`
|
||
|
would be created.
|
||
|
|
||
|
## Getting back metrics
|
||
|
|
||
|
Both the Clojure API and the Java API have functions to get back from a
|
||
|
`MetricRegistry` either the `Timer` objects or a selection of metric data, and
|
||
|
to filter this information based on url, url and method, or metric-id.
|
||
|
|
||
|
There are three different `Timer` objects: `UrlClientTimer` (which includes a
|
||
|
field for the url and `getUrl` method), `UrlAndMethodClientTimer` (which
|
||
|
includes a field for the url and a field for the method and accompanying
|
||
|
`getUrl` and `getMethod` methods), and `MetricIdClientTimer` (which includes a
|
||
|
field for the metric-id and accompanying `getMetricId` method). Each of these
|
||
|
timers also has an `isCategory` method that returns whether the timer is or is
|
||
|
not the provided `MetricCategory`.
|
||
|
|
||
|
Both the Clojure and Java APIs also include functions that return a list of
|
||
|
metrics data. This metrics data includes the `metric-name`, `count`, `mean`
|
||
|
(in ms), and `aggregate` (computed as `count * mean`) for each metric. In
|
||
|
addition, for `url` metrics the accompanying metrics data includes the `url`,
|
||
|
for `url-and-method` metrics it includes the `url` and `method`, and for
|
||
|
`metric-id` metrics it includes the `metric-id`.
|
||
|
|
||
|
The Java API returns `ClientMetricData` objects - of which there are three
|
||
|
types - `UrlClientMetricData`, `UrlAndMethodClientMetricData`, and
|
||
|
`MetricIdClientMetricData`. The Clojure API returns maps with keys for this
|
||
|
information.
|
||
|
|
||
|
Both APIs have functions for returning all metrics/metric data, for returning
|
||
|
all metrics/metrics data from a specific category, and for filtering
|
||
|
metrics/metrics data within a category.
|
||
|
|
||
|
## Java API
|
||
|
|
||
|
### Creating a client with metrics
|
||
|
To use metrics with the Java client, call `setMetricRegistry()` on the
|
||
|
`ClientOptions` before supplying them to create the client.
|
||
|
|
||
|
```java
|
||
|
MetricRegistry registry = new MetricRegistry();
|
||
|
ClientOptions options = new ClientOptions();
|
||
|
AsyncHttpClient client = Async.createClient(options);
|
||
|
```
|
||
|
|
||
|
(the same works with the `SyncHttpClient`).
|
||
|
|
||
|
Any client that is created with a `MetricRegistry` will automatically have
|
||
|
`url` and `url-and-method` metrics registered.
|
||
|
|
||
|
`getMetricRegistry()` can be called on a client to get the `MetricRegistry`
|
||
|
from it.
|
||
|
|
||
|
### Setting a metric-id
|
||
|
|
||
|
In addition to the `url` and `url-and-method` metrics, it is possible to set a
|
||
|
`metric-id` for a request that will create additional metrics.
|
||
|
|
||
|
A `metric-id` is an array of strings.
|
||
|
|
||
|
To set a `metric-id` for a request, use the `.setMetricId` method on the
|
||
|
`RequestOptions` class.
|
||
|
|
||
|
```java
|
||
|
RequestOptions options = new RequestOptions("https://foobar.com");
|
||
|
options.setMetricId(["foo", "bar", "baz"]);
|
||
|
client.get(options);
|
||
|
```
|
||
|
|
||
|
`getMetricId()` can be called on `RequestOptions` to get back the `metric-id`.
|
||
|
|
||
|
### Filtering metrics
|
||
|
|
||
|
To get all `Timer` objects registered for a `MetricRegistry`, use the
|
||
|
`getClientMetrics()` method in the `Metrics` class. This takes the
|
||
|
`MetricRegistry` as an argument and returns a `ClientTimerContainer` object.
|
||
|
|
||
|
The `ClientTimerContainer` object has three fields - `urlTimers`,
|
||
|
`urlAndMethodTimers`, and `metricIdTimers`. The list of `URLClientTimers` can
|
||
|
be retrieved from the `ClientTimerContainer` with the `getUrlTimers()` method.
|
||
|
A list of `URlAndMethodClientTimers` can be retrieved with the
|
||
|
`getUrlAndMethod()` method. A list of `MetricIdClientTimer`s can be retrieved
|
||
|
with the `getMetricIdTimers()` method.
|
||
|
|
||
|
To get all `MetricData` objects, representing data for each `Metric`
|
||
|
registered for a `MetricRegistry`, use the `getClientMetricsData()` methods in
|
||
|
the `Metric` class. This takes the `MetricRegistry` as an argument and returns
|
||
|
a `ClientMetricDataContainer` object. This object has a field for each type of
|
||
|
metric data - `urlData`, `urlAndMethodData`, and `metricIdData`. Each field
|
||
|
has an associated getter returning a list of the appropriate data object -
|
||
|
`UrlClientMetricData`, `UrlAndMethodClientMetricData`, and
|
||
|
`MetricIdClientMetricData`.
|
||
|
|
||
|
#### Filtering by URL
|
||
|
|
||
|
To get URL metrics and metrics data, use the `getClientMetricsByUrl()` and
|
||
|
`getClientMetricsDataByUrl()` methods in the `Metric` class.
|
||
|
|
||
|
Both of these take as arguments the `MetricRegistry` and a string url. If no
|
||
|
url is provided, return all url metrics. If no metrics are registered for that
|
||
|
url, return an empty list.
|
||
|
|
||
|
`getClientMetricsByUrl()` returns a list of `UrlClientTimer` objects.
|
||
|
`getClientMetricsDataByUrl` returns a list of `UrlClientMetricData` objects.
|
||
|
|
||
|
#### Filtering by URL and method
|
||
|
|
||
|
To get URL and method metrics and metrics data, use the
|
||
|
`getClientMetricsByUrlAndMethod()` and `getClientMetricsDataByUrlAndMethod()`
|
||
|
methods in the `Metric` class.
|
||
|
|
||
|
Both of these take as arguments the `MetricRegistry`, a string url, and a
|
||
|
string HTTP method. If no url or method is provided, will return all
|
||
|
url-and-method metrics. If no metrics are registered for that url and method,
|
||
|
returns an empty list.
|
||
|
|
||
|
`getClientMetricsByUrlAndMethod()` returns a list of `UrlAndMethodClientTimer`
|
||
|
objects. `getClientMetricsDataByUrlAndMethod` returns a list of
|
||
|
`UrlAndMethodClientMetricData` objects.
|
||
|
|
||
|
#### Filtering by metric-id
|
||
|
|
||
|
To get metric-id metrics and metrics data, use the
|
||
|
`getClientMetricsByMetricId()` and `getClientMetricsDataByMetricId()` methods
|
||
|
in the `Metric` class.
|
||
|
|
||
|
Both of these take as arguments the `MetricRegistry` and a metric-id - as an
|
||
|
array of 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.
|
||
|
|
||
|
`getClientMetricsByMetricId()` returns a list of `MetricIdClientTimer`
|
||
|
objects. `getClientMetricsDataByMetricId()` returns a list of
|
||
|
`MetricIdClientMetricData` objects.
|
||
|
|
||
|
## Clojure API
|
||
|
|
||
|
### Creating a client with metrics
|
||
|
To use metrics with the Clojure client, pass a `MetricRegistry` to it as part
|
||
|
of the options map:
|
||
|
|
||
|
```clojure
|
||
|
(async/create-client {:metric-registry (MetricRegistry.)})
|
||
|
```
|
||
|
|
||
|
(the same works with the `sync` client).
|
||
|
|
||
|
Any client that is created with a `MetricRegistry` will automatically have
|
||
|
`url` and `url-and-method` metrics registered.
|
||
|
|
||
|
`get-client-metric-registry` protocol function can be called on a client to
|
||
|
get the `MetricRegistry` from it.
|
||
|
|
||
|
### Setting a metric-id
|
||
|
|
||
|
In addition to the `url` and `url-and-method` metrics, it is possible to set a
|
||
|
`metric-id` for a request that will create additional metrics.
|
||
|
|
||
|
For the Clojure API, a `metric-id` is a vector of keywords.
|
||
|
|
||
|
To set a `metric-id` for a request, include it as an option in the request
|
||
|
options map.
|
||
|
|
||
|
```clojure
|
||
|
(common/get client "https://foobar.com" {:metric-id [:foo :bar :baz])
|
||
|
```
|
||
|
|
||
|
### Filtering metrics
|
||
|
|
||
|
To get all `Timer` objects registered for a `MetricRegistry`, use the
|
||
|
`get-client-metrics` function in the `metrics` namespace. This takes 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.
|
||
|
|
||
|
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.
|
||
|
|
||
|
#### Filtering by URL
|
||
|
|
||
|
To get URL metrics and metrics data, use the `get-client-metrics-by-url`
|
||
|
function and `get-client-metrics-data-by-url` in the `metrics` namespace.
|
||
|
|
||
|
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.
|
||
|
|
||
|
#### Filtering by URL and method
|
||
|
|
||
|
To get URL and method metrics and metrics data, use the
|
||
|
`get-client-metrics-by-url-and-method` and
|
||
|
`get-client-metrics-data-by-url-and-method` functions in the `metrics`
|
||
|
namespace.
|
||
|
|
||
|
Both of these take as arguments the `MetricRegistry`, a string url, and a
|
||
|
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.
|
||
|
|
||
|
#### Filtering by metric-id
|
||
|
|
||
|
To get metric-id metrics and metrics data, use the
|
||
|
`get-client-metrics-by-metric-id` and `get-client-metrics-data-by-metric-id`
|
||
|
functions in the `metrics` namespace.
|
||
|
|
||
|
Both of these take as arguments the `MetricRegistry` and a metric-id - as an
|
||
|
vector of keywords. 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.
|