Prometheus Java Client Library

Introduction

The Prometheus Java client library is a Java metrics library provided by the Prometheus community.

Instana's com.instana.plugin.java will automatically detect the Prometheus Java Client library, and the metrics are shown on the JVM dashboard.

This page describes the automatic instrumentation of the Prometheus Java client library, as well as Micrometer's Prometheus meter registry. If you are looking for a way to scrape metrics from a Prometheus exporter via HTTP, or to configure the Instana agent as a Prometheus remote write endpoint, see Prometheus.

Configuration

All configuration options are optional. Instana monitors metrics from the Prometheus Java client library with reasonable default values without requiring manual configuration.

However, you can overwrite the defaults by adding a prometheusMetricCollection section under com.instana.plugin.java in your agent's configuration.yaml file, as illustrated in the following example:

com.instana.plugin.java:
  prometheusMetricCollection:
    enabled: true
    limit: 200
    pollIntervalSeconds: 15
    excludeMetricNamesStartingWith:
      - jvm
      - process
    excludeMetricsMatching:
      - eu-central-1

The following configuration options are supported:

• enabled: Set this to false in order to disable monitoring of the Prometheus Java Client library. Default: true.
• limit: In order to avoid overload of the monitoring backend, we limit the number of metrics per JVM. You can use this configuration option to change the limit. Default: 200.
• pollIntervalSeconds: In general Instana offers 1 second resolution for metrics. However, you might have registered your own custom callbacks with the Prometheus Java Client library, and then every poll would result in calling your custom callbacks. In order to avoid potential overload of custom callbacks, we increased the poll interval for metrics from the Prometheus Java client library to 15 seconds by default. Use this configuration option to increase or decrease the poll interval. Default: 15.
• excludeMetricNamesStartingWith: List of metric name prefixes that should not be monitored. For example, the configuration above would exclude all metrics starting with jvm and all metrics starting with process, so you would not be able to see the following metrics:

  process_cpu_seconds_total 0.99
  process_open_fds 23.0
  jvm_threads_state{state="RUNNABLE"} 7.0
  jvm_threads_state{state="WAITING",} 3.0
  ```* `includeMetricNamesStartingWith`: Counterpart to `excludeMetricNamesStartingWith`. Only metrics starting with one of these prefixes will be included.
  

• excludeMetricsMatching: This is a more powerful alternative to excludeMetricNamesStartingWith: All metrics matching one of the list of regular expressions will be excluded. The regular expression is applied to the full metric string including labels, like counter_total{region="eu-central-1"}, not just to the metric name. The regular expression is not anchored, i.e. it can match anywhere in the middle of the string. For example, if you specify eu-central-1 in the excludeMetricsMatching list, the metric counter_total{region="eu-central-1"} will be excluded.
• includeMetricsMatching: Counterpart to excludeMetricsMatching. Only metrics matching one of the regular expressions in the list will be included, all other metrics will be excluded.

Monitoring Custom Collector Registries

By default, the Prometheus Java Client library registers all metrics with a global CollectorRegistry.defaultRegistry. In that case, Instana will find the registered metrics automatically and monitor them by default.

However, you might have your metrics registered with a custom CollectorRegistry in your code. In that case, you need to include a line of code to inform Instana about your custom collector registry. Instana provides a prometheus-java-library-integration dependency for that purpose, documentation can be found on github.com/instana/prometheus-java-library-integration.

Integration with Micrometer

You might not use the Prometheus Java Client library directly, but indirectly via Micrometer's Prometheus Meter Registry. If you want to keep that setup and see the Prometheus metrics in Instana, you can use our prometheus-java-library-integration to monitor the PrometheusMeterRegistry with Instana. Documentation can be found on github.com/instana/prometheus-java-library-integration.