Guide to Prometheus Java Client

1. Introduction

As distributed systems become more complex, monitoring becomes crucial to maintaining application performance and quickly identifying issues. One of the best tools for this is Prometheus, a robust open-source monitoring and alerting toolkit.

The Prometheus Java client allows us to instrument our applications with minimal effort by exposing real-time metrics for Prometheus to scrape and monitor.

We will explore how to use the Prometheus Java client library with Maven, including creating custom metrics and configuring an HTTP server to expose them. Additionally, we will cover the different metric types offered by the library, and provide practical examples that tie all these elements together.

2. Setting Up the Project

To get started with the Prometheus Java client, we’ll use Maven to manage our project’s dependencies. There are several essential dependencies that we need to add to our pom.xml file to enable Prometheus metrics collection and exposure:

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>prometheus-metrics-core</artifactId>
    <version>1.3.1</version>
</dependency>
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
    <version>1.3.1</version>
</dependency>
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>prometheus-metrics-exporter-httpserver</artifactId>
    <version>1.3.1</version>
</dependency>

We use the following dependencies prometheus-metrics-core is the core library of the Prometheus Java client. It provides the foundation for defining and registering custom metrics such as counters, gauges, histograms, etc.

prometheus-metrics-instrumentation-jvm provides out-of-the-box JVM metrics, including heap memory usage, garbage collection times, thread counts, and more.

prometheus-metrics-exporter-httpserver provides an embedded HTTP server to expose metrics in the Prometheus format. It creates a /metrics endpoint that Prometheus can scrape to collect data.

3. Creating and Exposing JVM Metrics

This section will cover how to expose the JVM metrics available through the Prometheus Java client. These metrics offer valuable insights into the performance of our application. Thanks to the prometheus-metrics-instrumentation-jvm dependency, we can easily register out-of-the-box JVM metrics without needing custom instrumentation:

public static void main(String[] args) throws InterruptedException, IOException {
    JvmMetrics.builder().register();

    HTTPServer server = HTTPServer.builder()
      .port(9400)
      .buildAndStart();

    System.out.println("HTTPServer listening on http://localhost:" + server.getPort() + "/metrics");

    Thread.currentThread().join();
}

To make the JVM metrics available to Prometheus, we exposed them over an HTTP endpoint. We used the prometheus-metrics-exporter-httpserver dependency to set up a simple HTTP server that listens on a port and serves the metrics.

We used the join() method to keep the main thread running indefinitely, ensuring that the HTTP server stays active so Prometheus can continuously scrape the metrics over time.

3.2. Testing the Application

Once the application is running, we can open a browser and navigate to http://localhost:9400/metrics to view the exposed metrics or we can use the curl command to fetch and inspect the metrics from the command line:

$ curl http://localhost:9400/metrics

We should see a list of JVM-related metrics in the Prometheus format, similar to this:

# HELP jvm_memory_bytes_used Used bytes of a given JVM memory area.
# TYPE jvm_memory_bytes_used gauge
jvm_memory_bytes_used{area="heap",} 5242880
jvm_memory_bytes_used{area="nonheap",} 2345678
# HELP jvm_gc_collection_seconds Time spent in a given JVM garbage collector in seconds.
# TYPE jvm_gc_collection_seconds summary
jvm_gc_collection_seconds_count{gc="G1 Young Generation",} 5
jvm_gc_collection_seconds_sum{gc="G1 Young Generation",} 0.087
...

The output displays various JVM metrics, such as memory usage, garbage collection details, and thread counts. Prometheus collects and analyzes these metrics, which are formatted in its dedicated exposition format.

4. Metric Types

In the Prometheus Java client, metrics are categorized into different types, each serving a specific purpose in measuring various aspects of our application’s behavior. These types are based on the OpenMetrics standard, which Prometheus adheres to.

Let’s explore the main metric types available in the Prometheus Java client and how they are typically used.

4.1. Counter

A Counter is a metric that only increments over time. We can use them to count the requests received, errors encountered, or tasks completed. Counters cannot be decreased, their values are reset only when the process restarts.

We can count the total number of HTTP requests our application handles:

Counter requestCounter = Counter.builder()
  .name("http_requests_total")
  .help("Total number of HTTP requests")
  .labelNames("method", "status")
  .register();

requestCounter.labelValues("GET", "200").inc();

We use labelNames and labelValues to add dimensions or context to our metrics. Labels in Prometheus are key-value pairs that allow us to differentiate between different categories of the same metric.

4.2. Gauge

A Gauge is a metric that can increase or decrease over time. We can use them to track values that change over time, like memory usage, temperature, or the number of active threads.

To measure the current memory usage or CPU load we would probably use a gauge:

Gauge memoryUsage = Gauge.builder()
  .name("memory_usage_bytes")
  .help("Current memory usage in bytes")
  .register();

memoryUsage.set(5000000);

4.3. Histogram

A Histogram is typically used to observe and track the distribution of values over time, such as request latencies or response sizes. It records pre-configured buckets and provides metrics on the number of observations in each bucket, the total count, and the sum of all observed values. This allows us to understand the data distribution and calculate percentiles or ranges.

Let’s walk through a detailed example that measures HTTP request durations and uses custom buckets to track specific ranges of response times:

Histogram requestLatency = Histogram.builder()
  .name("http_request_latency_seconds")
  .help("Tracks HTTP request latency in seconds")
  .labelNames("method")
  .register();

Random random = new Random();
for (int i = 0; i < 100; i++) {
    double latency = 0.1 + (3 * random.nextDouble());
    requestLatency.labelValues("GET").observe(latency);
}

We didn’t specify any custom buckets when creating the histogram therefore the library uses a set of default buckets. The default buckets cover exponential ranges of values, which suit many applications that measure durations or latencies. Specifically, the default bucket boundaries are as follows:

[5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s, +Inf]

When checking the result we might see output like this:

http_request_latency_seconds_bucket{method="GET",le="0.005"} 0
http_request_latency_seconds_bucket{method="GET",le="0.01"} 0
http_request_latency_seconds_bucket{method="GET",le="0.025"} 0
http_request_latency_seconds_bucket{method="GET",le="0.05"} 0
http_request_latency_seconds_bucket{method="GET",le="0.1"} 0
http_request_latency_seconds_bucket{method="GET",le="0.25"} 6
http_request_latency_seconds_bucket{method="GET",le="0.5"} 15
http_request_latency_seconds_bucket{method="GET",le="1.0"} 32
http_request_latency_seconds_bucket{method="GET",le="2.5"} 79
http_request_latency_seconds_bucket{method="GET",le="5.0"} 100
http_request_latency_seconds_bucket{method="GET",le="10.0"} 100
http_request_latency_seconds_bucket{method="GET",le="+Inf"} 100
http_request_latency_seconds_count{method="GET"} 100
http_request_latency_seconds_sum{method="GET"} 157.8138389516349

Each bucket shows how many observations fell into that range. For example, http_request_duration_seconds_bucket{le=”0.25″} shows that 6 requests took less than or equal to 250ms. The +Inf bucket captures all observations, so its count is the total number of observations.

4.4. Summary

A Summary is similar to a Histogram, but instead of using predefined buckets, it calculates quantiles to summarize the observed data. As a result, it becomes useful for tracking request latencies or response sizes. Furthermore, it helps us to determine key metrics like the median (50th percentile) or the 90th percentile:

Summary requestDuration = Summary.builder()
  .name("http_request_duration_seconds")
  .help("Tracks the duration of HTTP requests in seconds")
  .quantile(0.5, 0.05)
  .quantile(0.9, 0.01)
  .register();

for (int i = 0; i < 100; i++) {
    double duration = 0.05 + (2 * random.nextDouble());
    requestDuration.observe(duration);
}

We define two quantiles:

• 0.5 (50th percentile) approximates the median, with a 5% error.
• 0.9 (90th percentile) shows that 90% of the requests were faster than this value, with a 1% error.

When Prometheus scrapes the metrics, we’ll see output like this:

http_request_duration_seconds{quantile="0.5"} 1.3017345289221114
http_request_duration_seconds{quantile="0.9"} 1.8304437814581778
http_request_duration_seconds_count 100
http_request_duration_seconds_sum 110.5670284649691

The quantiles show the observed value at the 50th and 90th percentiles. In other words, 50% of requests took less than 1.3 seconds, and 90% took less than 1.9 seconds.

4.5. Info

An Info metric stores static labels about the application. It is used for version numbers, build information, or environment details. It is not a performance metric but a way to add informative metadata to the Prometheus output.

Info appInfo = Info.builder()
  .name("app_info")
  .help("Application version information")
  .labelNames("version", "build")
  .register();

appInfo.addLabelValues("1.0.0", "12345");

4.6. StateSet

A StateSet metric represents multiple states that can be either active or inactive. It is useful when we need to track different operational states of our application or feature flag statuses:

StateSet stateSet = StateSet.builder()
  .name("feature_flags")
  .help("Feature flags")
  .labelNames("env")
  .states("feature1")
  .register();

stateSet.labelValues("dev").setFalse("feature1");

5. Overview of Prometheus Metric Types

The Prometheus Java client provides various metrics to capture different dimensions of our application’s performance and behavior. Below is a summary table that outlines the key features of each metric type, including their purpose and usage examples:

6. Conclusion

In this article, we’ve explored how to effectively use the Prometheus Java client to monitor applications by instrumenting custom and JVM metrics. First, we covered setting up your project using Maven dependencies. Consequently, we moved on to exposing metrics via an HTTP endpoint. Afterward, we discussed key metric types such as Counters, Gauges, Histograms, and Summaries, each serving a distinct purpose in tracking various performance indicators.