clj-http-client/doc/metrics.md
2016-09-13 15:19:42 -07:00

12 KiB

Metrics

Both the Java client and the Clojure client have Dropwizard Metrics 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

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.

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.

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 MetricIdClientTimers 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:

(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.

(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 Timers 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 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.