Performance

This section has tips on how to use the Prometheus Java client in high performance applications.

For high performance applications, we recommend to specify label values only once, and then use the data point directly.

This applies to all metric types. Let’s use a counter as an example here:

Counter requestCount = Counter.builder()
    .name("requests_total")
    .help("total number of requests")
    .labelNames("path", "status")
    .register();

You could increment the counter above like this:

requestCount.labelValue("/", "200").inc();

However, the line above does not only increment the counter, it also looks up the label values to find the right data point.

In high performance applications you can optimize this by looking up the data point only once:

CounterDataPoint successfulCalls = requestCount.labelValues("/", "200");

Now, you can increment the data point directly, which is a highly optimized operation:

successfulCalls.inc();

By default, histograms maintain two representations under the hood: The classic histogram representation with static buckets, and the native histogram representation with dynamic buckets.

While this default provides the flexibility to scrape different representations at runtime, it comes at a cost, because maintaining multiple representations causes performance overhead.

In performance critical applications we recommend to use either the classic representation or the native representation, but not both.

You can either configure this in code for each histogram by calling classicOnly() or nativeOnly(), or you use the corresponding config options.

One way to do this is with system properties in the command line when you start your application

java -Dio.prometheus.metrics.histogramClassicOnly=true my-app.jar

or

java -Dio.prometheus.metrics.histogramNativeOnly=true my-app.jar

If you don’t want to add a command line parameter every time you start your application, you can add a prometheus.properties file to your classpath (put it in the src/main/resources/ directory so that it gets packed into your JAR file). The prometheus.properties file should have the following line:

io.prometheus.metrics.histogramClassicOnly=true

or

io.prometheus.metrics.histogramNativeOnly=true

Future releases will add more configuration options, like support for configuration via environment variableIO_PROMETHEUS_METRICS_HISTOGRAM_NATIVE_ONLY=true.