or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

counter.mdenumeration.mdexemplars.mdgauge.mdhistogram.mdindex.mdinfo.mdregistry.mdsummary.md
tile.json

tessl/maven-io-prometheus--simpleclient

Core instrumentation library for the Prometheus Java client, providing fundamental metric types for application monitoring

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.prometheus/simpleclient@0.16.x

To install, run

npx @tessl/cli install tessl/maven-io-prometheus--simpleclient@0.16.0

index.mddocs/

Prometheus Java Client - Simple Client

The Prometheus Java simpleclient library provides the core instrumentation classes for monitoring Java applications. It offers fundamental metric types (Counter, Gauge, Histogram, Summary, Info, Enumeration) for application metrics, with support for labels, exemplars, and thread-safe operations. The library is designed with zero runtime dependencies and provides standardized ways to instrument code, collect metrics, and expose them for scraping by Prometheus servers.

Package Information

  • Package Name: io.prometheus:simpleclient
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient</artifactId>
    <version>0.16.0</version>
</dependency>

For Gradle:

implementation 'io.prometheus:simpleclient:0.16.0'

Core Imports

import io.prometheus.client.*;

For specific metric types:

import io.prometheus.client.Counter;
import io.prometheus.client.Gauge;
import io.prometheus.client.Histogram;
import io.prometheus.client.Summary;
import io.prometheus.client.Info;
import io.prometheus.client.Enumeration;
import io.prometheus.client.CollectorRegistry;

Basic Usage

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

public class Example {
    // Counter for tracking total requests
    static final Counter requestsTotal = Counter.build()
        .name("requests_total")
        .help("Total requests")
        .register();
    
    // Gauge for current in-progress requests  
    static final Gauge inProgressRequests = Gauge.build()
        .name("inprogress_requests")
        .help("Requests in progress")
        .register();
    
    // Histogram for request duration tracking
    static final Histogram requestDuration = Histogram.build()
        .name("request_duration_seconds")
        .help("Request duration in seconds")
        .register();
    
    public void handleRequest() {
        requestsTotal.inc();
        inProgressRequests.inc();
        
        Histogram.Timer timer = requestDuration.startTimer();
        try {
            // Handle request logic here
        } finally {
            timer.observeDuration();
            inProgressRequests.dec();
        }
    }
}

Architecture

The Prometheus Java client is built around several key components:

  • Metric Types: Counter, Gauge, Histogram, Summary, Info, and Enumeration provide different measurement patterns
  • Registry System: CollectorRegistry manages metric collection and export
  • Label Support: Multi-dimensional metrics with label-based children
  • Builder Pattern: Fluent configuration API for all metric types
  • Thread Safety: All operations are thread-safe for concurrent use
  • Exemplar Integration: Support for linking metrics to distributed traces

Capabilities

Counter Metrics

Counter metrics track counts and totals that only increase (except on resets). Perfect for tracking requests, errors, completed tasks, and cumulative values.

public class Counter extends SimpleCollector<Counter.Child> {
    public static Counter.Builder build();
    public static Counter.Builder build(String name, String help);
    public void inc();
    public void inc(double amt);
    public void incWithExemplar(String... exemplarLabels);
    public void incWithExemplar(double amt, String... exemplarLabels);
    public double get();
}

Counter Metrics

Gauge Metrics

Gauge metrics track values that can go up and down, like memory usage, queue sizes, temperature, or active connections.

public class Gauge extends SimpleCollector<Gauge.Child> {
    public static Gauge.Builder build();
    public static Gauge.Builder build(String name, String help);
    public void inc();
    public void inc(double amt);
    public void dec();
    public void dec(double amt);
    public void set(double val);
    public void setToCurrentTime();
    public Timer startTimer();
    public double get();
}

Gauge Metrics

Histogram Metrics

Histogram metrics track distributions of values like request latencies or response sizes, organizing observations into configurable buckets.

public class Histogram extends SimpleCollector<Histogram.Child> {
    public static Histogram.Builder build();
    public static Histogram.Builder build(String name, String help);
    public void observe(double amt);
    public void observeWithExemplar(double amt, String... exemplarLabels);
    public Timer startTimer();
    public double time(Runnable timeable);
    public <E> E time(Callable<E> timeable);
}

Histogram Metrics

Summary Metrics

Summary metrics track quantiles and distributions with configurable sliding time windows and precise quantile calculations.

public class Summary extends SimpleCollector<Summary.Child> {
    public static Summary.Builder build();
    public static Summary.Builder build(String name, String help);
    public void observe(double amt);
    public Timer startTimer();
    public double time(Runnable timeable);
    public <E> E time(Callable<E> timeable);
}

Summary Metrics

Info Metrics

Info metrics provide key-value metadata pairs for build information, version details, and configuration data.

public class Info extends SimpleCollector<Info.Child> {
    public static Info.Builder build();
    public static Info.Builder build(String name, String help);
    public void info(String... labelPairs);
}

Info Metrics

Enumeration Metrics

Enumeration metrics track which of a set of states something is in, perfect for status tracking and state machines.

public class Enumeration extends SimpleCollector<Enumeration.Child> {
    public static Enumeration.Builder build();
    public static Enumeration.Builder build(String name, String help);
    public void state(String state);
    public void state(Enum<?> state);
}

Enumeration Metrics

Registry Management

The CollectorRegistry manages metric registration, collection, and provides access to metric samples for export.

public class CollectorRegistry {
    public static final CollectorRegistry defaultRegistry;
    public void register(Collector m);
    public void unregister(Collector m);
    public void clear();
    public Enumeration<MetricFamilySamples> metricFamilySamples();
    public Double getSampleValue(String name);
}

Registry Management

Exemplar Support

Exemplars link individual metric observations to distributed trace data, enabling correlation between metrics and traces.

public class Exemplar {
    public Exemplar(double value, String... labels);
    public Exemplar(double value, Long timestampMs, String... labels);
    public double getValue();
    public Long getTimestampMs();
    public String[] getLabels();
}

Exemplar Support

Types

Base Types

public abstract class Collector {
    /** Nanoseconds per second constant for time conversions */
    public static final double NANOSECONDS_PER_SECOND = 1E9;
    
    /** Milliseconds per second constant for time conversions */
    public static final double MILLISECONDS_PER_SECOND = 1E3;
    
    /**
     * Collect all metric samples from this collector
     * @return List of MetricFamilySamples
     */
    public abstract List<MetricFamilySamples> collect();
    
    /**
     * Collect filtered metric samples from this collector
     * @param sampleNameFilter Predicate to filter sample names
     * @return List of filtered MetricFamilySamples
     */
    public List<MetricFamilySamples> collect(Predicate<String> sampleNameFilter);
    
    /**
     * Register this collector with the default registry
     * @return This collector for method chaining
     */
    public <T extends Collector> T register();
    
    /**
     * Register this collector with specified registry
     * @param registry Registry to register with
     * @return This collector for method chaining
     */
    public <T extends Collector> T register(CollectorRegistry registry);
    
    /**
     * Sanitize metric name for Prometheus compatibility
     * @param metricName Raw metric name
     * @return Sanitized metric name
     */
    public static String sanitizeMetricName(String metricName);
    
    /**
     * Convert double to Prometheus Go-style string
     * @param d Double value to convert
     * @return String representation
     */
    public static String doubleToGoString(double d);
    
    public enum Type {
        UNKNOWN, COUNTER, GAUGE, STATE_SET, INFO, HISTOGRAM, GAUGE_HISTOGRAM, SUMMARY
    }
    
    /**
     * Interface for collectors that provide metric descriptions
     */
    public interface Describable {
        /**
         * Describe the metrics this collector exposes
         * @return List of MetricFamilySamples for metric descriptions
         */
        List<MetricFamilySamples> describe();
    }
}

public abstract class SimpleCollector<Child> extends Collector {
    /** Full metric name including namespace and subsystem */
    protected final String fullname;
    
    /** Help text for this metric */
    protected final String help;
    
    /** Unit for this metric */
    protected final String unit;
    
    /** Label names for this metric */
    protected final List<String> labelNames;
    
    /**
     * Get child instance for specific label values
     * @param labelValues Values for each defined label name
     * @return Child instance for these label values
     */
    public Child labels(String... labelValues);
    
    /**
     * Remove child for specific label values
     * @param labelValues Values identifying child to remove
     */
    public void remove(String... labelValues);
    
    /**
     * Remove all children
     */
    public void clear();
    
    /**
     * Set child instance for specific label values
     * @param child Child instance to set
     * @param labelValues Label values for this child
     * @return This collector for method chaining
     */
    public <T extends Collector> T setChild(Child child, String... labelValues);
    
    /**
     * Create new child instance - implemented by subclasses
     * @return New child instance
     */
    protected abstract Child newChild();
}

public interface Predicate<T> {
    /**
     * Test if input matches this predicate
     * @param t Input value to test
     * @return true if input matches predicate
     */
    boolean test(T t);
}

Builder Pattern Types

public abstract static class Builder<B extends Builder<B, C>, C> {
    public B name(String name);
    public B help(String help);
    public B labelNames(String... labelNames);
    public B namespace(String namespace);
    public B subsystem(String subsystem);
    public B unit(String unit);
    public C register();
    public C register(CollectorRegistry registry);
    public abstract C create();
}

Simple Timer Utility

Utility class for precise duration measurement in seconds without direct metric registration.

public class SimpleTimer {
    /**
     * Create a new SimpleTimer starting at current time
     */
    public SimpleTimer();
    
    /**
     * Get elapsed time since timer creation
     * @return Duration in seconds as double
     */
    public double elapsedSeconds();
    
    /**
     * Calculate elapsed seconds from nanosecond timestamps
     * @param startNanos Start time in nanoseconds
     * @param endNanos End time in nanoseconds
     * @return Duration in seconds
     */
    public static double elapsedSecondsFromNanos(long startNanos, long endNanos);
}

Sample and Family Types

public static class MetricFamilySamples {
    public final String name;
    public final String unit;
    public final Type type;
    public final String help;
    public final List<Sample> samples;
    
    /**
     * Filter samples by predicate
     * @param sampleNameFilter Predicate to test sample names
     * @return Filtered MetricFamilySamples or null if no matches
     */
    public MetricFamilySamples filter(Predicate<String> sampleNameFilter);
    
    /**
     * Get all reserved sample names for this metric family
     * @return Array of reserved sample names
     */
    public String[] getNames();
    
    public static class Sample {
        public final String name;
        public final List<String> labelNames;
        public final List<String> labelValues;
        public final double value;
        public final Exemplar exemplar;
        public final Long timestampMs;
    }
}

MetricFamily Helper Classes

For custom collectors and advanced use cases.

public class CounterMetricFamily extends Collector.MetricFamilySamples {
    /**
     * Create counter metric family without labels
     * @param name Metric name (without _total suffix)
     * @param help Help text
     * @param value Counter value
     */
    public CounterMetricFamily(String name, String help, double value);
    
    /**
     * Create counter metric family with labels
     * @param name Metric name (without _total suffix)  
     * @param help Help text
     * @param labelNames List of label names
     */
    public CounterMetricFamily(String name, String help, List<String> labelNames);
    
    /**
     * Add metric sample with label values
     * @param labelValues Values for each label
     * @param value Counter value
     * @return This instance for method chaining
     */
    public CounterMetricFamily addMetric(List<String> labelValues, double value);
}

public class GaugeMetricFamily extends Collector.MetricFamilySamples {
    public GaugeMetricFamily(String name, String help, double value);
    public GaugeMetricFamily(String name, String help, List<String> labelNames);
    public GaugeMetricFamily addMetric(List<String> labelValues, double value);
}

public class SummaryMetricFamily extends Collector.MetricFamilySamples {
    public SummaryMetricFamily(String name, String help, double count, double sum);
    public SummaryMetricFamily(String name, String help, List<String> labelNames);
    public SummaryMetricFamily addMetric(List<String> labelValues, double count, double sum);
    public SummaryMetricFamily addMetric(List<String> labelValues, double count, double sum, List<Double> quantiles);
}

Utility Interfaces

public interface Predicate<T> {
    /**
     * Test if the given input matches this predicate
     * @param t Input to test
     * @return true if input matches predicate
     */
    boolean test(T t);
}

public class SampleNameFilter {
    /**
     * Static utility methods for creating sample name filters
     */
}