Integration of Prometheus Metrics in Java: simpleclient Library

Prometheus Metrics in Java: Complete Guide to the simpleclient Library

Prometheus is a powerful open-source monitoring and alerting system that has become the de facto standard in the Cloud Native world. For Java developers, there are several libraries for integration, but the official simpleclient library (also known as prometheus/client_java) is the most popular and well-maintained. In this article, we will thoroughly cover how to add Prometheus metrics to a Java application using this library.

What is simpleclient?

simpleclient is the official Java client for Prometheus, providing a simple and efficient way to create and export metrics. The library supports four main Prometheus metric types:

• Counter — a monotonically increasing value (e.g., number of requests).
• Gauge — a value that can arbitrarily change (e.g., current CPU load).
• Histogram — distribution of values across predefined "buckets" (e.g., response time).
• Summary — quantiles of observed values (e.g., p50, p99 of response time).

Installation and Setup

To get started, add the following dependencies to your pom.xml (Maven) or build.gradle (Gradle).

Maven

<dependency>    <groupId>io.prometheus</groupId>    <artifactId>simpleclient</artifactId>    <version>0.16.0</version></dependency>

<!-- For exporting metrics via HTTP --><dependency>    <groupId>io.prometheus</groupId>    <artifactId>simpleclient_httpserver</artifactId>    <version>0.16.0</version></dependency>

Gradle

implementation 'io.prometheus:simpleclient:0.16.0'implementation 'io.prometheus:simpleclient_httpserver:0.16.0'

Creating and Using Metrics

Let's look at an example of creating all the main metric types in one class.

import io.prometheus.client.Counter;import io.prometheus.client.Gauge;import io.prometheus.client.Histogram;import io.prometheus.client.Summary;

public class MetricsExample {

    // 1. Counter: number of processed requests    static final Counter requestsCounter = Counter.build()        .name("app_requests_total")        .help("Total number of processed requests.")        .labelNames("endpoint", "method")        .register();

    // 2. Gauge: current number of active users    static final Gauge activeUsersGauge = Gauge.build()        .name("app_active_users")        .help("Current number of active users.")        .register();

    // 3. Histogram: request duration in milliseconds    static final Histogram requestDurationHistogram = Histogram.build()        .name("app_request_duration_ms")        .help("Request duration in milliseconds.")        .buckets(10, 50, 100, 200, 500, 1000, 5000)        .register();

    // 4. Summary: quantiles of execution time    static final Summary requestDurationSummary = Summary.build()        .name("app_request_duration_summary_ms")        .help("Request duration summary in milliseconds.")        .quantile(0.5, 0.05)   // p50 with 5% acceptable error        .quantile(0.99, 0.01)  // p99 with 1% acceptable error        .register();

    public static void main(String[] args) throws Exception {        // Simulating request processing        for (int i = 0; i < 100; i++) {            processRequest("/api/users", "GET");        }

        // Starting HTTP server for metric export        new HTTPServer(9090);        System.out.println("Metrics server started