Monitoring 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 a DistributionFitter. 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 LabelDescriptor of 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 a Counter, 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 MetricWriter that talks to your backend. A StackdriverWriter is provided. A MetricReporter needs to be constructed from the MetricWriter:

  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 ThreadFactoryBuilder from Guava:

  ThreadFactory threadFactory = ThreadFactoryBuilder().setDaemon(true).build();

  Then in you main method, 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.