JarCastingMonitoring Client Library for Java
This is not an official Google product.
This library provides an API that is powerful and java idiomatic for configuring and publishing application metrics. A reference implementation using Stackdriver Monitoring API v3 is included, but other monitoring backend implementations can also be used.
Most of other monitoring libraries available are low-level and are tied directly to the backend. This library provides type safety, retry logic and an backend-agnostic approach to Java metrics instrumentation.
Basic concepts
-
Metric Types
Counters: monotonically increasing integers. e. g. number of total requests.EventMetrics: data points in certain distribution, used in combination with aDistributionFitter. e. g. latency distribution, request size distribution.Gauges: state indicators, used with a callback function to query the state. e. g. number of active connections, current memory usage.
In general, cumulative values are counters and cumulative probability distributions, and non-cumulative values are gauges.
A metric class consists of typed values (for type safety) and string labels. The labels are used to identify a specific metric time series, for example, a counter for the number of requests can have label "client_ip_address" and "protocol". In this example, all requests coming from the same client IP and using the same protocol would be counted together.
Metrics are modeled after Stackdriver Metrics.
Importing the library
The most recent release is v1.0.5.
The Maven group ID is com.google.monitoring-client. The artifact ID is metrics for the main library, and stackdriver for the stackdriver backend writer. We also provide a contrib library that is useful if you want to make test assertions on certain metric types with Google's truth library.
To add a dependency on the metrics library using Maven:
<dependency>
<groupId>com.google.monitoring-client</groupId>
<artifactId>metrics</artifactId>
<version>1.0.5</version>
</dependency>
Using the library
-
Registering Metrics
To register a metric, specify the name is should be registered (in style of an URL path), and the set of
LabelDescriptorof the metric. For example to register a counter:IncrementableMetric myCounter = MetricRegistryImpl.getDefault() .newIncrementableMetric( "/path/to/record/metrics", "description", "value_unit", labels);
-
Recording Metrics
To record a data point to the metric we just registered, call its recording method, specify the labels (required), and value (required for
EventMetric). In case of aCounter, just supplying the labels is sufficient as the value is implicitly increased by one.myCounter.increment("label1", "label2", "label3");
-
Exporting Metrics
To export metrics to a monitoring backend, you need configure your backend accordingly and implement a
MetricWriterthat talks to your backend. AStackdriverWriteris provided. AMetricReporterneeds to be constructed from theMetricWriter:MetricReporter metricReporter = new MetricReporter( metricWriter, writeIntervalInSeconds, threadFactory);
A thread factory is needed so that the metric reporter can run in the background periodically to export recorded metrics (in batch) to the backend. It is recommended to set the thread to daemon mode so that it does not interfere with JVM shutdown. You can use
ThreadFactoryBuilderfrom Guava:ThreadFactory threadFactory = ThreadFactoryBuilder().setDaemon(true).build();
Then in you
mainmethod, start the metric reporter asynchronously:metricReporter.get().startAsync().awaitRunning(10, TimeUnit.SECONDS);
The reporter will now run in the background and automatically exports metrics at the given
writeIntervalInSeconds.
