MACRO NEPAL
Metrics Collection Library in Java
awiskar acharya
November 10, 2025
12:44 pm

A comprehensive metrics collection library supporting Gauges, Counters, Timers, Histograms, and Meters with multiple reporting backends and advanced features.

Complete Implementation

1. Core Metrics Interfaces and Base Classes

package com.metrics.core;
import java.util.*;
import java.util.concurrent.*;
import java.util.concurrent.atomic.*;
import java.time.Instant;
import java.io.Closeable;
/**
* Core metrics interfaces and base implementation
*/
public interface Metric {
String getName();
Map<String, String> getTags();
MetricType getType();
Instant getCreatedTime();
}
public enum MetricType {
COUNTER, GAUGE, TIMER, HISTOGRAM, METER, SET
}
public interface Countable {
long getCount();
}
/**
* Base metric class
*/
public abstract class AbstractMetric implements Metric {
protected final String name;
protected final Map<String, String> tags;
protected final Instant createdTime;
protected final MetricType type;
public AbstractMetric(String name, Map<String, String> tags, MetricType type) {
this.name = name;
this.tags = tags != null ? new ConcurrentHashMap<>(tags) : new ConcurrentHashMap<>();
this.createdTime = Instant.now();
this.type = type;
}
@Override
public String getName() { return name; }
@Override
public Map<String, String> getTags() { return new HashMap<>(tags); }
@Override
public MetricType getType() { return type; }
@Override
public Instant getCreatedTime() { return createdTime; }
public void addTag(String key, String value) {
tags.put(key, value);
}
public void removeTag(String key) {
tags.remove(key);
}
}

2. Counter Implementation

/**
* Counter metric - monotonically increasing value
*/
public class Counter extends AbstractMetric implements Countable {
private final AtomicLong count;
private final AtomicLong lastUpdated;
public Counter(String name) {
this(name, null);
}
public Counter(String name, Map<String, String> tags) {
super(name, tags, MetricType.COUNTER);
this.count = new AtomicLong(0);
this.lastUpdated = new AtomicLong(System.currentTimeMillis());
}
public void increment() {
increment(1);
}
public void increment(long delta) {
if (delta < 0) {
throw new IllegalArgumentException("Counter can only be incremented by non-negative values");
}
count.addAndGet(delta);
lastUpdated.set(System.currentTimeMillis());
}
public void decrement() {
decrement(1);
}
public void decrement(long delta) {
if (delta < 0) {
throw new IllegalArgumentException("Counter can only be decremented by non-negative values");
}
count.addAndGet(-delta);
lastUpdated.set(System.currentTimeMillis());
}
public void reset() {
count.set(0);
lastUpdated.set(System.currentTimeMillis());
}
@Override
public long getCount() {
return count.get();
}
public long getLastUpdated() {
return lastUpdated.get();
}
public CounterSnapshot getSnapshot() {
return new CounterSnapshot(getCount(), Instant.ofEpochMilli(lastUpdated.get()));
}
/**
* Immutable counter snapshot
*/
public static class CounterSnapshot {
private final long count;
private final Instant timestamp;
public CounterSnapshot(long count, Instant timestamp) {
this.count = count;
this.timestamp = timestamp;
}
public long getCount() { return count; }
public Instant getTimestamp() { return timestamp; }
}
}

3. Gauge Implementation

/**
* Gauge metric - instantaneous measurement of a value
*/
public class Gauge extends AbstractMetric {
private final Callable<Double> valueSupplier;
private volatile double lastValue;
private final AtomicLong lastUpdated;
public Gauge(String name, Callable<Double> valueSupplier) {
this(name, valueSupplier, null);
}
public Gauge(String name, Callable<Double> valueSupplier, Map<String, String> tags) {
super(name, tags, MetricType.GAUGE);
this.valueSupplier = valueSupplier;
this.lastUpdated = new AtomicLong(System.currentTimeMillis());
this.lastValue = Double.NaN;
}
public double getValue() {
try {
double value = valueSupplier.call();
lastValue = value;
lastUpdated.set(System.currentTimeMillis());
return value;
} catch (Exception e) {
System.err.println("Error getting gauge value for " + name + ": " + e.getMessage());
return lastValue;
}
}
public long getLastUpdated() {
return lastUpdated.get();
}
public GaugeSnapshot getSnapshot() {
return new GaugeSnapshot(getValue(), Instant.ofEpochMilli(lastUpdated.get()));
}
/**
* Simple number gauge
*/
public static class NumberGauge extends Gauge {
private final AtomicDouble value;
public NumberGauge(String name) {
this(name, null);
}
public NumberGauge(String name, Map<String, String> tags) {
super(name, () -> 0.0, tags);
this.value = new AtomicDouble(0.0);
// Override the value supplier to use our atomic double
try {
var field = Gauge.class.getDeclaredField("valueSupplier");
field.setAccessible(true);
field.set(this, (Callable<Double>) value::get);
} catch (Exception e) {
throw new RuntimeException("Failed to create NumberGauge", e);
}
}
public void setValue(double newValue) {
value.set(newValue);
}
public double getCurrentValue() {
return value.get();
}
}
/**
* Cached gauge that updates value on demand but caches for a period
*/
public static class CachedGauge extends Gauge {
private final long cacheTimeoutMs;
private volatile double cachedValue;
private volatile long lastCacheUpdate;
public CachedGauge(String name, Callable<Double> valueSupplier, long cacheTimeoutMs) {
this(name, valueSupplier, cacheTimeoutMs, null);
}
public CachedGauge(String name, Callable<Double> valueSupplier, 
long cacheTimeoutMs, Map<String, String> tags) {
super(name, valueSupplier, tags);
this.cacheTimeoutMs = cacheTimeoutMs;
this.cachedValue = Double.NaN;
this.lastCacheUpdate = 0;
}
@Override
public double getValue() {
long now = System.currentTimeMillis();
if (now - lastCacheUpdate > cacheTimeoutMs) {
try {
cachedValue = valueSupplier.call();
lastCacheUpdate = now;
} catch (Exception e) {
System.err.println("Error updating cached gauge " + getName() + ": " + e.getMessage());
}
}
return cachedValue;
}
}
/**
* Immutable gauge snapshot
*/
public static class GaugeSnapshot {
private final double value;
private final Instant timestamp;
public GaugeSnapshot(double value, Instant timestamp) {
this.value = value;
this.timestamp = timestamp;
}
public double getValue() { return value; }
public Instant getTimestamp() { return timestamp; }
}
}

4. Timer Implementation

/**
* Timer metric - measures duration and rate of events
*/
public class Timer extends AbstractMetric implements Countable {
private final Histogram histogram;
private final Meter meter;
private final Clock clock;
public Timer(String name) {
this(name, null, new ExponentiallyDecayingReservoir());
}
public Timer(String name, Map<String, String> tags) {
this(name, tags, new ExponentiallyDecayingReservoir());
}
public Timer(String name, Map<String, String> tags, Reservoir reservoir) {
super(name, tags, MetricType.TIMER);
this.histogram = new Histogram(name + ".histogram", tags, reservoir);
this.meter = new Meter(name + ".meter", tags);
this.clock = Clock.DEFAULT;
}
public TimerContext start() {
return new TimerContext(this, clock.getTick());
}
public long time(Runnable operation) {
long startTime = clock.getTick();
try {
operation.run();
} finally {
update(clock.getTick() - startTime);
}
return clock.getTick() - startTime;
}
public <T> T time(Callable<T> operation) {
long startTime = clock.getTick();
try {
return operation.call();
} catch (Exception e) {
throw new RuntimeException(e);
} finally {
update(clock.getTick() - startTime);
}
}
public void update(long duration, TimeUnit unit) {
update(unit.toNanos(duration));
}
public void update(long durationNanos) {
if (durationNanos >= 0) {
histogram.update(durationNanos);
meter.mark();
}
}
public double getFifteenMinuteRate() {
return meter.getFifteenMinuteRate();
}
public double getFiveMinuteRate() {
return meter.getFiveMinuteRate();
}
public double getOneMinuteRate() {
return meter.getOneMinuteRate();
}
public double getMeanRate() {
return meter.getMeanRate();
}
public Snapshot getSnapshot() {
return histogram.getSnapshot();
}
@Override
public long getCount() {
return histogram.getCount();
}
public long getSum() {
return histogram.getSum();
}
public double getMean() {
return histogram.getMean();
}
public double getStdDev() {
return histogram.getStdDev();
}
public double getMax() {
return histogram.getMax();
}
public double getMin() {
return histogram.getMin();
}
/**
* Timer context for timing blocks of code
*/
public static class TimerContext implements Closeable {
private final Timer timer;
private final long startTime;
private volatile boolean stopped;
public TimerContext(Timer timer, long startTime) {
this.timer = timer;
this.startTime = startTime;
this.stopped = false;
}
public long stop() {
if (!stopped) {
stopped = true;
long elapsed = timer.clock.getTick() - startTime;
timer.update(elapsed);
return elapsed;
}
return 0;
}
@Override
public void close() {
stop();
}
}
public TimerSnapshot getTimerSnapshot() {
return new TimerSnapshot(
getCount(),
getSum(),
getMean(),
getStdDev(),
getMin(),
getMax(),
getSnapshot(),
getMeanRate(),
getOneMinuteRate(),
getFiveMinuteRate(),
getFifteenMinuteRate(),
Instant.now()
);
}
/**
* Immutable timer snapshot
*/
public static class TimerSnapshot {
private final long count;
private final long sum;
private final double mean;
private final double stdDev;
private final double min;
private final double max;
private final Snapshot snapshot;
private final double meanRate;
private final double oneMinuteRate;
private final double fiveMinuteRate;
private final double fifteenMinuteRate;
private final Instant timestamp;
public TimerSnapshot(long count, long sum, double mean, double stdDev, 
double min, double max, Snapshot snapshot,
double meanRate, double oneMinuteRate, 
double fiveMinuteRate, double fifteenMinuteRate,
Instant timestamp) {
this.count = count;
this.sum = sum;
this.mean = mean;
this.stdDev = stdDev;
this.min = min;
this.max = max;
this.snapshot = snapshot;
this.meanRate = meanRate;
this.oneMinuteRate = oneMinuteRate;
this.fiveMinuteRate = fiveMinuteRate;
this.fifteenMinuteRate = fifteenMinuteRate;
this.timestamp = timestamp;
}
// Getters
public long getCount() { return count; }
public long getSum() { return sum; }
public double getMean() { return mean; }
public double getStdDev() { return stdDev; }
public double getMin() { return min; }
public double getMax() { return max; }
public Snapshot getSnapshot() { return snapshot; }
public double getMeanRate() { return meanRate; }
public double getOneMinuteRate() { return oneMinuteRate; }
public double getFiveMinuteRate() { return fiveMinuteRate; }
public double getFifteenMinuteRate() { return fifteenMinuteRate; }
public Instant getTimestamp() { return timestamp; }
}
}

5. Histogram Implementation

/**
* Histogram metric - statistical distribution of values
*/
public class Histogram extends AbstractMetric implements Countable {
private final Reservoir reservoir;
private final AtomicLong count;
private final AtomicLong sum;
public Histogram(String name, Reservoir reservoir) {
this(name, null, reservoir);
}
public Histogram(String name, Map<String, String> tags, Reservoir reservoir) {
super(name, tags, MetricType.HISTOGRAM);
this.reservoir = reservoir;
this.count = new AtomicLong(0);
this.sum = new AtomicLong(0);
}
public void update(int value) {
update((long) value);
}
public void update(long value) {
count.incrementAndGet();
sum.addAndGet(value);
reservoir.update(value);
}
public void update(double value) {
count.incrementAndGet();
sum.addAndGet((long) value);
reservoir.update((long) value);
}
@Override
public long getCount() {
return count.get();
}
public long getSum() {
return sum.get();
}
public double getMean() {
long currentCount = count.get();
if (currentCount == 0) {
return 0.0;
}
return (double) sum.get() / currentCount;
}
public double getStdDev() {
Snapshot snapshot = getSnapshot();
return snapshot.getStdDev();
}
public double getMax() {
Snapshot snapshot = getSnapshot();
return snapshot.getMax();
}
public double getMin() {
Snapshot snapshot = getSnapshot();
return snapshot.getMin();
}
public Snapshot getSnapshot() {
return reservoir.getSnapshot();
}
public HistogramSnapshot getHistogramSnapshot() {
return new HistogramSnapshot(
getCount(),
getSum(),
getMean(),
getStdDev(),
getMin(),
getMax(),
getSnapshot(),
Instant.now()
);
}
/**
* Immutable histogram snapshot
*/
public static class HistogramSnapshot {
private final long count;
private final long sum;
private final double mean;
private final double stdDev;
private final double min;
private final double max;
private final Snapshot snapshot;
private final Instant timestamp;
public HistogramSnapshot(long count, long sum, double mean, double stdDev,
double min, double max, Snapshot snapshot, Instant timestamp) {
this.count = count;
this.sum = sum;
this.mean = mean;
this.stdDev = stdDev;
this.min = min;
this.max = max;
this.snapshot = snapshot;
this.timestamp = timestamp;
}
// Getters
public long getCount() { return count; }
public long getSum() { return sum; }
public double getMean() { return mean; }
public double getStdDev() { return stdDev; }
public double getMin() { return min; }
public double getMax() { return max; }
public Snapshot getSnapshot() { return snapshot; }
public Instant getTimestamp() { return timestamp; }
}
}

6. Meter Implementation

/**
* Meter metric - measures rate of events
*/
public class Meter extends AbstractMetric implements Countable {
private static final long TICK_INTERVAL = TimeUnit.SECONDS.toNanos(5);
private static final int MAX_AGE = 15; // 15 minutes in ticks
private final AtomicLong count;
private final long startTime;
private final AtomicLong lastTick;
private final EWMA m1Rate;   // 1-minute rate
private final EWMA m5Rate;   // 5-minute rate
private final EWMA m15Rate;  // 15-minute rate
private final Clock clock;
public Meter(String name) {
this(name, null);
}
public Meter(String name, Map<String, String> tags) {
super(name, tags, MetricType.METER);
this.count = new AtomicLong(0);
this.startTime = this.clock.getTick();
this.lastTick = new AtomicLong(startTime);
this.m1Rate = EWMA.oneMinuteEWMA();
this.m5Rate = EWMA.fiveMinuteEWMA();
this.m15Rate = EWMA.fifteenMinuteEWMA();
this.clock = Clock.DEFAULT;
}
public void mark() {
mark(1);
}
public void mark(long n) {
tickIfNecessary();
count.addAndGet(n);
m1Rate.update(n);
m5Rate.update(n);
m15Rate.update(n);
}
private void tickIfNecessary() {
long oldTick = lastTick.get();
long newTick = clock.getTick();
long age = newTick - oldTick;
if (age > TICK_INTERVAL) {
long newIntervalStartTick = newTick - age % TICK_INTERVAL;
if (lastTick.compareAndSet(oldTick, newIntervalStartTick)) {
long requiredTicks = age / TICK_INTERVAL;
for (long i = 0; i < requiredTicks; i++) {
m1Rate.tick();
m5Rate.tick();
m15Rate.tick();
}
}
}
}
@Override
public long getCount() {
return count.get();
}
public double getFifteenMinuteRate() {
tickIfNecessary();
return m15Rate.getRate(TimeUnit.SECONDS);
}
public double getFiveMinuteRate() {
tickIfNecessary();
return m5Rate.getRate(TimeUnit.SECONDS);
}
public double getOneMinuteRate() {
tickIfNecessary();
return m1Rate.getRate(TimeUnit.SECONDS);
}
public double getMeanRate() {
if (getCount() == 0) {
return 0.0;
}
long elapsed = clock.getTick() - startTime;
return convertNsRate(getCount() / (double) elapsed);
}
private double convertNsRate(double ratePerNs) {
return ratePerNs * (double) TimeUnit.SECONDS.toNanos(1);
}
public MeterSnapshot getMeterSnapshot() {
return new MeterSnapshot(
getCount(),
getMeanRate(),
getOneMinuteRate(),
getFiveMinuteRate(),
getFifteenMinuteRate(),
Instant.now()
);
}
/**
* Immutable meter snapshot
*/
public static class MeterSnapshot {
private final long count;
private final double meanRate;
private final double oneMinuteRate;
private final double fiveMinuteRate;
private final double fifteenMinuteRate;
private final Instant timestamp;
public MeterSnapshot(long count, double meanRate, double oneMinuteRate,
double fiveMinuteRate, double fifteenMinuteRate, Instant timestamp) {
this.count = count;
this.meanRate = meanRate;
this.oneMinuteRate = oneMinuteRate;
this.fiveMinuteRate = fiveMinuteRate;
this.fifteenMinuteRate = fifteenMinuteRate;
this.timestamp = timestamp;
}
// Getters
public long getCount() { return count; }
public double getMeanRate() { return meanRate; }
public double getOneMinuteRate() { return oneMinuteRate; }
public double getFiveMinuteRate() { return fiveMinuteRate; }
public double getFifteenMinuteRate() { return fifteenMinuteRate; }
public Instant getTimestamp() { return timestamp; }
}
}

7. Reservoir and Sampling Implementations

/**
* Reservoir interface for sampling data
*/
public interface Reservoir {
int size();
void update(long value);
Snapshot getSnapshot();
}
/**
* Statistical snapshot
*/
public interface Snapshot {
double getValue(double quantile);
long[] getValues();
int size();
long getMax();
long getMin();
double getMean();
double getStdDev();
double getMedian();
double get75thPercentile();
double get95thPercentile();
double get98thPercentile();
double get99thPercentile();
double get999thPercentile();
}
/**
* Exponentially decaying reservoir
*/
public class ExponentiallyDecayingReservoir implements Reservoir {
private static final int DEFAULT_SIZE = 1028;
private static final double DEFAULT_ALPHA = 0.015;
private static final long RESCALE_THRESHOLD = TimeUnit.HOURS.toNanos(1);
private final ConcurrentSkipListMap<Double, Long> values;
private final AtomicLong count;
private final double alpha;
private final int size;
private final AtomicLong startTime;
private final AtomicLong nextScaleTime;
private final Clock clock;
public ExponentiallyDecayingReservoir() {
this(DEFAULT_SIZE, DEFAULT_ALPHA);
}
public ExponentiallyDecayingReservoir(int size, double alpha) {
this.values = new ConcurrentSkipListMap<>();
this.count = new AtomicLong(0);
this.alpha = alpha;
this.size = size;
this.startTime = new AtomicLong(Clock.DEFAULT.getTick());
this.nextScaleTime = new AtomicLong(startTime.get() + RESCALE_THRESHOLD);
this.clock = Clock.DEFAULT;
}
@Override
public int size() {
return Math.min(size, (int) count.get());
}
@Override
public void update(long value) {
update(value, clock.getTick());
}
public void update(long value, long timestamp) {
rescaleIfNeeded();
double weight = weight(timestamp - startTime.get());
double priority = weight / ThreadLocalRandom.current().nextDouble();
long newCount = count.incrementAndGet();
if (newCount <= size) {
values.put(priority, value);
} else {
Double first = values.firstKey();
if (first < priority && values.putIfAbsent(priority, value) == null) {
while (values.remove(first) == null) {
first = values.firstKey();
}
}
}
}
private double weight(long time) {
return Math.exp(alpha * time);
}
private void rescaleIfNeeded() {
long now = clock.getTick();
long next = nextScaleTime.get();
if (now >= next) {
rescale(now, next);
}
}
private void rescale(long now, long next) {
if (nextScaleTime.compareAndSet(next, now + RESCALE_THRESHOLD)) {
long oldStartTime = startTime.get();
startTime.set(now);
double scalingFactor = Math.exp(-alpha * (now - oldStartTime));
if (scalingFactor != 0) {
ArrayList<Double> keys = new ArrayList<>(values.keySet());
for (Double key : keys) {
Long value = values.remove(key);
if (value != null) {
values.put(key * scalingFactor, value);
}
}
}
}
}
@Override
public Snapshot getSnapshot() {
rescaleIfNeeded();
return new WeightedSnapshot(values);
}
}
/**
* Weighted snapshot implementation
*/
public class WeightedSnapshot implements Snapshot {
private final long[] values;
private final double[] weights;
private final double[] quantiles;
public WeightedSnapshot(ConcurrentSkipListMap<Double, Long> values) {
List<Long> valueList = new ArrayList<>(values.values());
List<Double> weightList = new ArrayList<>(values.keySet());
this.values = new long[valueList.size()];
this.weights = new double[weightList.size()];
this.quantiles = new double[valueList.size()];
// Sort by value
List<Pair<Long, Double>> pairs = new ArrayList<>();
for (int i = 0; i < valueList.size(); i++) {
pairs.add(new Pair<>(valueList.get(i), weightList.get(i)));
}
pairs.sort(Comparator.comparing(Pair::getKey));
double sum = 0.0;
for (int i = 0; i < pairs.size(); i++) {
Pair<Long, Double> pair = pairs.get(i);
this.values[i] = pair.getKey();
this.weights[i] = pair.getValue();
sum += pair.getValue();
}
// Normalize weights and calculate quantiles
double runningSum = 0.0;
for (int i = 0; i < weights.length; i++) {
weights[i] /= sum;
runningSum += weights[i];
quantiles[i] = runningSum;
}
}
@Override
public double getValue(double quantile) {
if (quantile < 0.0 || quantile > 1.0 || values.length == 0) {
return 0.0;
}
if (values.length == 1) {
return values[0];
}
for (int i = 0; i < quantiles.length; i++) {
if (quantiles[i] >= quantile) {
return values[i];
}
}
return values[values.length - 1];
}
@Override
public long[] getValues() {
return Arrays.copyOf(values, values.length);
}
@Override
public int size() {
return values.length;
}
@Override
public long getMax() {
if (values.length == 0) return 0;
long max = values[0];
for (long value : values) {
if (value > max) max = value;
}
return max;
}
@Override
public long getMin() {
if (values.length == 0) return 0;
long min = values[0];
for (long value : values) {
if (value < min) min = value;
}
return min;
}
@Override
public double getMean() {
if (values.length == 0) return 0.0;
double sum = 0.0;
double totalWeight = 0.0;
for (int i = 0; i < values.length; i++) {
sum += values[i] * weights[i];
totalWeight += weights[i];
}
return sum / totalWeight;
}
@Override
public double getStdDev() {
if (values.length <= 1) return 0.0;
double mean = getMean();
double variance = 0.0;
double totalWeight = 0.0;
for (int i = 0; i < values.length; i++) {
double diff = values[i] - mean;
variance += weights[i] * diff * diff;
totalWeight += weights[i];
}
return Math.sqrt(variance / totalWeight);
}
@Override
public double getMedian() {
return getValue(0.5);
}
@Override
public double get75thPercentile() {
return getValue(0.75);
}
@Override
public double get95thPercentile() {
return getValue(0.95);
}
@Override
public double get98thPercentile() {
return getValue(0.98);
}
@Override
public double get99thPercentile() {
return getValue(0.99);
}
@Override
public double get999thPercentile() {
return getValue(0.999);
}
private static class Pair<K, V> {
private final K key;
private final V value;
public Pair(K key, V value) {
this.key = key;
this.value = value;
}
public K getKey() { return key; }
public V getValue() { return value; }
}
}
/**
* EWMA (Exponentially Weighted Moving Average)
*/
public class EWMA {
private static final int INTERVAL = 5;
private static final double SECONDS_PER_MINUTE = 60.0;
private static final int ONE_MINUTE = 1;
private static final int FIVE_MINUTES = 5;
private static final int FIFTEEN_MINUTES = 15;
private static final double M1_ALPHA = 1 - Math.exp(-INTERVAL / SECONDS_PER_MINUTE / ONE_MINUTE);
private static final double M5_ALPHA = 1 - Math.exp(-INTERVAL / SECONDS_PER_MINUTE / FIVE_MINUTES);
private static final double M15_ALPHA = 1 - Math.exp(-INTERVAL / SECONDS_PER_MINUTE / FIFTEEN_MINUTES);
private volatile boolean initialized = false;
private volatile double rate = 0.0;
private final AtomicLong uncounted = new AtomicLong(0);
private final double alpha;
private final double interval;
public static EWMA oneMinuteEWMA() {
return new EWMA(M1_ALPHA, INTERVAL);
}
public static EWMA fiveMinuteEWMA() {
return new EWMA(M5_ALPHA, INTERVAL);
}
public static EWMA fifteenMinuteEWMA() {
return new EWMA(M15_ALPHA, INTERVAL);
}
public EWMA(double alpha, long interval) {
this.alpha = alpha;
this.interval = interval;
}
public void update(long n) {
uncounted.addAndGet(n);
}
public void tick() {
long count = uncounted.getAndSet(0);
double instantRate = count / interval;
if (initialized) {
rate += (alpha * (instantRate - rate));
} else {
rate = instantRate;
initialized = true;
}
}
public double getRate(TimeUnit rateUnit) {
return rate * (double) rateUnit.toNanos(1);
}
}
/**
* Clock abstraction for testing
*/
public interface Clock {
long getTick();
Clock DEFAULT = new Clock() {
@Override
public long getTick() {
return System.nanoTime();
}
};
}
/**
* Atomic double implementation
*/
class AtomicDouble extends Number {
private final AtomicLong value;
public AtomicDouble() {
this(0.0);
}
public AtomicDouble(double initialValue) {
value = new AtomicLong(Double.doubleToLongBits(initialValue));
}
public final void set(double newValue) {
value.set(Double.doubleToLongBits(newValue));
}
public final double get() {
return Double.longBitsToDouble(value.get());
}
public final double getAndSet(double newValue) {
return Double.longBitsToDouble(value.getAndSet(Double.doubleToLongBits(newValue)));
}
public final boolean compareAndSet(double expect, double update) {
return value.compareAndSet(Double.doubleToLongBits(expect), 
Double.doubleToLongBits(update));
}
@Override
public int intValue() {
return (int) get();
}
@Override
public long longValue() {
return (long) get();
}
@Override
public float floatValue() {
return (float) get();
}
@Override
public double doubleValue() {
return get();
}
}

8. Metrics Registry and Management

/**
* Central metrics registry
*/
public class MetricsRegistry {
private final ConcurrentMap<String, Metric> metrics;
private final List<MetricsReporter> reporters;
private final ScheduledExecutorService scheduler;
private static volatile MetricsRegistry instance;
private MetricsRegistry() {
this.metrics = new ConcurrentHashMap<>();
this.reporters = new CopyOnWriteArrayList<>();
this.scheduler = Executors.newScheduledThreadPool(2);
}
public static MetricsRegistry getInstance() {
if (instance == null) {
synchronized (MetricsRegistry.class) {
if (instance == null) {
instance = new MetricsRegistry();
}
}
}
return instance;
}
public Counter counter(String name) {
return counter(name, null);
}
public Counter counter(String name, Map<String, String> tags) {
return (Counter) metrics.computeIfAbsent(
getKey(name, tags), 
k -> new Counter(name, tags)
);
}
public Gauge gauge(String name, Callable<Double> valueSupplier) {
return gauge(name, valueSupplier, null);
}
public Gauge gauge(String name, Callable<Double> valueSupplier, Map<String, String> tags) {
return (Gauge) metrics.computeIfAbsent(
getKey(name, tags),
k -> new Gauge(name, valueSupplier, tags)
);
}
public Gauge.NumberGauge numberGauge(String name) {
return numberGauge(name, null);
}
public Gauge.NumberGauge numberGauge(String name, Map<String, String> tags) {
return (Gauge.NumberGauge) metrics.computeIfAbsent(
getKey(name, tags),
k -> new Gauge.NumberGauge(name, tags)
);
}
public Timer timer(String name) {
return timer(name, null);
}
public Timer timer(String name, Map<String, String> tags) {
return (Timer) metrics.computeIfAbsent(
getKey(name, tags),
k -> new Timer(name, tags)
);
}
public Histogram histogram(String name) {
return histogram(name, null);
}
public Histogram histogram(String name, Map<String, String> tags) {
return (Histogram) metrics.computeIfAbsent(
getKey(name, tags),
k -> new Histogram(name, tags, new ExponentiallyDecayingReservoir())
);
}
public Meter meter(String name) {
return meter(name, null);
}
public Meter meter(String name, Map<String, String> tags) {
return (Meter) metrics.computeIfAbsent(
getKey(name, tags),
k -> new Meter(name, tags)
);
}
public void remove(String name) {
metrics.remove(name);
}
public void remove(String name, Map<String, String> tags) {
metrics.remove(getKey(name, tags));
}
public Map<String, Metric> getMetrics() {
return new HashMap<>(metrics);
}
public <T extends Metric> T getMetric(String name, Class<T> metricClass) {
return getMetric(name, null, metricClass);
}
@SuppressWarnings("unchecked")
public <T extends Metric> T getMetric(String name, Map<String, String> tags, Class<T> metricClass) {
Metric metric = metrics.get(getKey(name, tags));
if (metric != null && metricClass.isInstance(metric)) {
return (T) metric;
}
return null;
}
public void addReporter(MetricsReporter reporter) {
reporters.add(reporter);
}
public void startReporters(long interval, TimeUnit unit) {
for (MetricsReporter reporter : reporters) {
scheduler.scheduleAtFixedRate(() -> {
try {
reporter.report(getMetrics());
} catch (Exception e) {
System.err.println("Error in metrics reporter: " + e.getMessage());
}
}, 0, interval, unit);
}
}
public void stopReporters() {
scheduler.shutdown();
}
private String getKey(String name, Map<String, String> tags) {
if (tags == null || tags.isEmpty()) {
return name;
}
StringBuilder key = new StringBuilder(name);
tags.entrySet().stream()
.sorted(Map.Entry.comparingByKey())
.forEach(entry -> key.append(";").append(entry.getKey()).append("=").append(entry.getValue()));
return key.toString();
}
}
/**
* Metrics reporter interface
*/
public interface MetricsReporter {
void report(Map<String, Metric> metrics);
String getName();
}
/**
* Console metrics reporter
*/
public class ConsoleReporter implements MetricsReporter {
private final PrintStream output;
public ConsoleReporter() {
this(System.out);
}
public ConsoleReporter(PrintStream output) {
this.output = output;
}
@Override
public void report(Map<String, Metric> metrics) {
output.println("=== Metrics Report ===");
output.printf("%-40s %-10s %-20s%n", "Name", "Type", "Value");
output.println("----------------------------------------");
for (Map.Entry<String, Metric> entry : metrics.entrySet()) {
Metric metric = entry.getValue();
String value = getMetricValue(metric);
output.printf("%-40s %-10s %-20s%n", 
metric.getName(), metric.getType(), value);
}
output.println();
}
private String getMetricValue(Metric metric) {
switch (metric.getType()) {
case COUNTER:
return String.valueOf(((Counter) metric).getCount());
case GAUGE:
return String.format("%.2f", ((Gauge) metric).getValue());
case TIMER:
Timer timer = (Timer) metric;
return String.format("count=%d, mean=%.2fms", 
timer.getCount(), timer.getMean() / 1_000_000.0);
case HISTOGRAM:
Histogram histogram = (Histogram) metric;
return String.format("count=%d, mean=%.2f", 
histogram.getCount(), histogram.getMean());
case METER:
Meter meter = (Meter) metric;
return String.format("count=%d, rate=%.2f/s", 
meter.getCount(), meter.getOneMinuteRate());
default:
return "N/A";
}
}
@Override
public String getName() {
return "ConsoleReporter";
}
}
/**
* JMX metrics reporter
*/
public class JmxReporter implements MetricsReporter {
private final MBeanServer mBeanServer;
private final Map<String, ObjectName> registeredBeans;
public JmxReporter() {
this.mBeanServer = ManagementFactory.getPlatformMBeanServer();
this.registeredBeans = new ConcurrentHashMap<>();
}
@Override
public void report(Map<String, Metric> metrics) {
for (Map.Entry<String, Metric> entry : metrics.entrySet()) {
String key = entry.getKey();
Metric metric = entry.getValue();
try {
ObjectName objectName = getObjectName(metric);
if (!registeredBeans.containsKey(key)) {
mBeanServer.registerMBean(createMBean(metric), objectName);
registeredBeans.put(key, objectName);
}
} catch (Exception e) {
System.err.println("Error registering JMX bean for metric " + key + ": " + e.getMessage());
}
}
// Clean up removed metrics
Set<String> currentKeys = new HashSet<>(metrics.keySet());
for (String key : registeredBeans.keySet()) {
if (!currentKeys.contains(key)) {
try {
mBeanServer.unregisterMBean(registeredBeans.get(key));
registeredBeans.remove(key);
} catch (Exception e) {
System.err.println("Error unregistering JMX bean: " + e.getMessage());
}
}
}
}
private ObjectName getObjectName(Metric metric) throws Exception {
String domain = "com.metrics";
String name = metric.getName().replaceAll("[^a-zA-Z0-9-_]", ".");
Map<String, String> tags = metric.getTags();
StringBuilder objectName = new StringBuilder(domain).append(":type=").append(metric.getType());
objectName.append(",name=").append(name);
for (Map.Entry<String, String> tag : tags.entrySet()) {
objectName.append(",").append(tag.getKey()).append("=").append(tag.getValue());
}
return new ObjectName(objectName.toString());
}
private Object createMBean(Metric metric) {
// Create appropriate MBean based on metric type
// This is a simplified implementation
return new StandardMBean(metric, Metric.class);
}
@Override
public String getName() {
return "JmxReporter";
}
}

9. Usage Examples and Demo

/**
* Demo and usage examples
*/
public class MetricsDemo {
public static void main(String[] args) throws Exception {
MetricsRegistry registry = MetricsRegistry.getInstance();
// Add reporters
registry.addReporter(new ConsoleReporter());
registry.addReporter(new JmxReporter());
// Start reporting every 10 seconds
registry.startReporters(10, TimeUnit.SECONDS);
// Create different types of metrics
Counter requestCounter = registry.counter("http.requests", 
Map.of("method", "GET", "status", "200"));
Gauge memoryGauge = registry.gauge("jvm.memory.used", () -> 
(double) (Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory()));
Timer requestTimer = registry.timer("http.request.duration");
Meter errorMeter = registry.meter("http.errors");
Histogram responseSizeHistogram = registry.histogram("http.response.size");
// Simulate some activity
simulateWebTraffic(requestCounter, requestTimer, errorMeter, responseSizeHistogram);
// Let it run for a while
Thread.sleep(60000);
// Stop reporters
registry.stopReporters();
}
private static void simulateWebTraffic(Counter counter, Timer timer, Meter errorMeter, 
Histogram responseSizeHistogram) {
ScheduledExecutorService executor = Executors.newScheduledThreadPool(5);
// Simulate successful requests
executor.scheduleAtFixedRate(() -> {
try (Timer.TimerContext context = timer.start()) {
counter.increment();
responseSizeHistogram.update(ThreadLocalRandom.current().nextInt(100, 5000));
Thread.sleep(ThreadLocalRandom.current().nextInt(10, 200));
} catch (Exception e) {
errorMeter.mark();
}
}, 0, 100, TimeUnit.MILLISECONDS);
// Simulate occasional errors
executor.scheduleAtFixedRate(() -> {
if (ThreadLocalRandom.current().nextDouble() < 0.1) {
errorMeter.mark();
}
}, 0, 1, TimeUnit.SECONDS);
}
}
/**
* Builder for metric names with tags
*/
public class MetricBuilder {
private final String name;
private final Map<String, String> tags;
private MetricBuilder(String name) {
this.name = name;
this.tags = new HashMap<>();
}
public static MetricBuilder name(String name) {
return new MetricBuilder(name);
}
public MetricBuilder tag(String key, String value) {
tags.put(key, value);
return this;
}
public Counter counter() {
return MetricsRegistry.getInstance().counter(name, tags);
}
public Timer timer() {
return MetricsRegistry.getInstance().timer(name, tags);
}
public Meter meter() {
return MetricsRegistry.getInstance().meter(name, tags);
}
public Histogram histogram() {
return MetricsRegistry.getInstance().histogram(name, tags);
}
}
// Example usage of MetricBuilder
class ApplicationMetrics {
private static final Counter USER_LOGINS = MetricBuilder.name("user.logins")
.tag("component", "auth")
.counter();
private static final Timer DB_QUERY_TIMER = MetricBuilder.name("db.query.duration")
.tag("component", "database")
.timer();
public void userLogin(String username) {
USER_LOGINS.increment();
try (Timer.TimerContext context = DB_QUERY_TIMER.start()) {
// Perform database query
Thread.sleep(50);
} catch (Exception e) {
// Handle error
}
}
}

Features

  • Multiple Metric Types: Counters, Gauges, Timers, Histograms, Meters
  • High Performance: Atomic operations, efficient data structures
  • Statistical Sampling: Exponentially decaying reservoirs for percentiles
  • Tag Support: Key-value tags for dimensional metrics
  • Multiple Reporting: Console, JMX, and extensible reporter interface
  • Thread-Safe: All operations are thread-safe
  • Memory Efficient: Reservoir sampling for high-cardinality data
  • EWMA Rates: Exponentially weighted moving averages for meter rates

Usage Examples

Basic Counter

Counter counter = MetricsRegistry.getInstance().counter("requests");
counter.increment();

Timer for Code Blocks

Timer timer = MetricsRegistry.getInstance().timer("operation.duration");
try (Timer.TimerContext context = timer.start()) {
// Your code here
}

Gauge for Dynamic Values

Gauge gauge = MetricsRegistry.getInstance().gauge("queue.size", 
() -> (double) queue.size());

Meter for Rate Measurement

Meter meter = MetricsRegistry.getInstance().meter("errors");
meter.mark(); // When error occurs

This comprehensive metrics library provides production-ready instrumentation for Java applications with support for all standard metric types and multiple reporting backends.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper