tessl/maven-io-prometheus--simpleclient

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

—

Pending

Overview

Eval results

Files

Counter Metrics

Name: tessl/maven-io-prometheus--simpleclient
Author: tessl

Counter metrics track counts and totals that only increase (except on resets). Use counters for tracking requests processed, errors occurred, bytes transferred, or any other monotonically increasing values.

Capabilities

Counter Creation

Create counter metrics using the builder pattern with required name and help text.

/**
 * Create a new Counter builder
 * @return Builder instance for configuration
 */
public static Counter.Builder build();

/**
 * Create a new Counter builder with required fields
 * @param name The metric name (will have _total suffix added)
 * @param help The help text describing the metric
 * @return Builder instance for configuration
 */
public static Counter.Builder build(String name, String help);

Usage Example:

import io.prometheus.client.Counter;

// Basic counter
Counter requestsTotal = Counter.build()
    .name("requests_total")
    .help("Total number of requests")
    .register();

// Counter with labels
Counter httpRequestsTotal = Counter.build()
    .name("http_requests_total") 
    .help("Total HTTP requests")
    .labelNames("method", "status")
    .register();

Counter Builder Configuration

Configure counter metrics with labels, namespace, and exemplar support.

public static class Builder extends SimpleCollector.Builder<Builder, Counter> {
    /**
     * Enable exemplar support with default sampler
     * @return Builder for method chaining
     */
    public Builder withExemplars();
    
    /**
     * Disable exemplar support
     * @return Builder for method chaining  
     */
    public Builder withoutExemplars();
    
    /**
     * Configure custom exemplar sampler
     * @param exemplarSampler Custom sampler implementation
     * @return Builder for method chaining
     */
    public Builder withExemplarSampler(CounterExemplarSampler exemplarSampler);
}

Counter Operations

Increment counter values with optional exemplar support for trace correlation.

/**
 * Increment counter by 1
 */
public void inc();

/**
 * Increment counter by specified amount
 * @param amt Amount to increment (must be non-negative)
 * @throws IllegalArgumentException if amt is negative
 */
public void inc(double amt);

/**
 * Increment by 1 with exemplar for trace correlation
 * @param exemplarLabels Trace labels as name/value pairs
 */
public void incWithExemplar(String... exemplarLabels);

/**
 * Increment by amount with exemplar for trace correlation
 * @param amt Amount to increment (must be non-negative)
 * @param exemplarLabels Trace labels as name/value pairs
 * @throws IllegalArgumentException if amt is negative
 */
public void incWithExemplar(double amt, String... exemplarLabels);

/**
 * Increment with exemplar using Map for labels
 * @param amt Amount to increment
 * @param exemplarLabels Map of label names to values
 */
public void incWithExemplar(double amt, Map<String, String> exemplarLabels);

/**
 * Increment by 1 with exemplar using Map for labels
 * @param exemplarLabels Map of label names to values
 */
public void incWithExemplar(Map<String, String> exemplarLabels);

/**
 * Get current counter value
 * @return Current counter value
 */
public double get();

/**
 * Collect metric samples from this counter
 * @return List of MetricFamilySamples
 */
public List<MetricFamilySamples> collect();

/**
 * Describe this counter metric
 * @return List of MetricFamilySamples for description
 */
public List<MetricFamilySamples> describe();

Usage Examples:

// Basic increment operations
requestsTotal.inc();
requestsTotal.inc(5.0);

// Labeled counters
httpRequestsTotal.labels("GET", "200").inc();
httpRequestsTotal.labels("POST", "404").inc(2);

// With exemplars for tracing
requestsTotal.incWithExemplar("trace_id", "abc123");
requestsTotal.incWithExemplar(3.0, "trace_id", "def456", "span_id", "789");

// Using Map for exemplar labels
Map<String, String> traceLabels = new HashMap<>();
traceLabels.put("trace_id", "xyz789");
requestsTotal.incWithExemplar(1.0, traceLabels);

Labeled Counter Operations

Work with multi-dimensional counters using label values to create distinct time series.

/**
 * Get counter child for specific label values
 * @param labelValues Values for each label name (must match count)
 * @return Counter.Child instance for the label combination
 * @throws IllegalArgumentException if wrong number of labels
 */
public Counter.Child labels(String... labelValues);

/**
 * Remove counter child for specific label values
 * @param labelValues Values identifying the child to remove
 */
public void remove(String... labelValues);

/**
 * Remove all counter children
 */
public void clear();

Counter Child Operations

Counter.Child provides the same increment operations for labeled instances.

public static class Child {
    /**
     * Default constructor
     */
    public Child();
    
    /**
     * Constructor with exemplar configuration
     * @param exemplarsEnabled Whether exemplars are enabled for this child
     * @param exemplarSampler Custom exemplar sampler or null for default
     */
    public Child(Boolean exemplarsEnabled, CounterExemplarSampler exemplarSampler);
    
    /** Increment child counter by 1 */
    public void inc();
    
    /** Increment child counter by amount */
    public void inc(double amt);
    
    /** Increment with exemplar support */
    public void incWithExemplar(String... exemplarLabels);
    public void incWithExemplar(double amt, String... exemplarLabels);
    public void incWithExemplar(double amt, Map<String, String> exemplarLabels);
    public void incWithExemplar(Map<String, String> exemplarLabels);
    
    /** Get current child counter value */
    public double get();
    
    /** Get creation timestamp in milliseconds */
    public long created();
}

Usage Example:

// Working with labeled counters
Counter.Child getRequests = httpRequestsTotal.labels("GET", "200");
getRequests.inc();
getRequests.inc(3.0);

// Get current values
double totalRequests = requestsTotal.get();
double getRequestCount = getRequests.get();

// Remove specific label combination
httpRequestsTotal.remove("GET", "404");

// Clear all children
httpRequestsTotal.clear();

Important Notes

Counter Naming Convention

Counters automatically handle the _total suffix:

If you specify requests_total as the name, it becomes requests internally
When exported, it appears as requests_total for Prometheus compatibility
Always use meaningful names that indicate what is being counted

Thread Safety

All counter operations are thread-safe and designed for high-concurrency environments:

// Safe to call from multiple threads simultaneously
Counter.Builder.create().name("concurrent_ops").help("Ops").register();
Counter concurrentCounter = Counter.build().name("thread_safe").help("Example").register();

// Multiple threads can safely increment
concurrentCounter.inc(); // Thread-safe
concurrentCounter.labels("method", "POST").inc(); // Thread-safe

Error Handling

Counters validate input and throw appropriate exceptions:

try {
    counter.inc(-1.0); // Throws IllegalArgumentException
} catch (IllegalArgumentException e) {
    // Handle negative increment attempt
}

try {
    counter.labels("too", "many", "labels"); // Throws if label count mismatch
} catch (IllegalArgumentException e) {
    // Handle incorrect label count
}

Install with Tessl CLI

npx tessl i tessl/maven-io-prometheus--simpleclient

docs