Prometheus JVM Client

It supports Java, Clojure, Scala, JRuby, and anything else that runs on the JVM.

Using

Assets

If you use Maven, you can simply reference the assets below. The latest version can be found on in the maven repository for io.prometheus and io.prometheus.client.utility.

Simpleclient

<!-- The client -->
<dependency>
  <groupId>io.prometheus</groupId>
  <artifactId>simpleclient</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Hotspot JVM metrics-->
<dependency>
  <groupId>io.prometheus</groupId>
  <artifactId>simpleclient_hotspot</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Exposition servlet-->
<dependency>
  <groupId>io.prometheus</groupId>
  <artifactId>simpleclient_servlet</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Pushgateway exposition-->
<dependency>
  <groupId>io.prometheus</groupId>
  <artifactId>simpleclient_pushgateway</artifactId>
  <version>0.0.6</version>
</dependency>

Original client

<!-- The client -->
<dependency>
  <groupId>io.prometheus</groupId>
  <artifactId>client</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Hotspot 'jvmstat/perfdata' metrics -->
<dependency>
  <groupId>io.prometheus.client.utility</groupId>
  <artifactId>jvmstat</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Hotspot 'jvmstat/perfdata' metrics -->
<dependency>
  <groupId>io.prometheus.client.utility</groupId>
  <artifactId>jvmstat</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Hotspot VM metrics -->
<dependency>
  <groupId>io.prometheus.client.utility</groupId>
  <artifactId>metrics</artifactId>
  <version>0.0.6</version>
</dependency>
<!-- Exposition servlet -->
<dependency>
  <groupId>io.prometheus.client.utility</groupId>
  <artifactId>servlet</artifactId>
  <version>0.0.6</version>
</dependency>

Getting Started

There are canonical examples defined in the class definition Javadoc of the client packages.

Documentation

The client is canonically documented with Javadoc. Running the following will produce local documentation in apidocs directories for you to read.

$ mvn package

If you use the Mavenized version of the Prometheus client, you can also instruct Maven to download the Javadoc and source artifacts.

Alternatively, you can also look at the generated Java Client Github Project Page, but the raw Javadoc in Java source in version control should be treated as the canonical form of documentation.

Maintenance of this Library

This suite is built and managed by Maven, and the artifacts are hosted on the Sonatype OSS Asset Repository.

All contributions to this library must follow, as far as practical, the prevalent patterns in the library for consistency and the following style guide: Google Java Style. Depending upon your development environment, you may be able to find an automatic formatter and adherence checker that follows these rules.

Building

$ mvn compile

Testing

$ mvn test

Please note that tests on Travis may be unreliable due to the absence of installed Maven artifacts. Ensure that the current snapshot version is deployed to Sonatype OSS Repository.

Testing the simple spawning example

If you just want to verify that the client library can be built and run in a standalone JVM process, you can use the examples/simple module. This example spawns a Jetty HTTP server and exposes a few sample metrics that can be scraped locally. To run it:

1. Build the shaded jar:

    $ mvn -pl examples/simple clean package
   

2. Launch the example process (this spawns Jetty on port 1234 by default):

    $ java -jar examples/simple/target/simple-0.0.9-SNAPSHOT-jar-with-dependencies.jar
   

You should see log output indicating that the sample application started. You can then curl http://localhost:1234/metrics in another terminal to confirm that the process is up and exposing metrics.

Deployment

These steps below are only useful if you are in a release engineering capacity and want to publicize these changes for external users. You will also need to have your local Maven setup correctly along with valid and public GPG key and adequate authorization on the Sonatype OSS Repository to submit new artifacts, be they staging or release ones.

You should read the Sonatype OSS Maven Repository Usage Guide before performing any of the following:

Staging

$  mvn clean deploy -DperformRelease=true

Release

$ mvn release:clean -DperformRelease=true
$ mvn release:prepare -DperformRelease=true
$ mvn release:perform -DperformRelease=true

Documentation

Documentation can also be released to the public via the Github Pages subproduct through the magic gh-pages branch for a Github project. Documentation is generated via the following command:

$ mvn javadoc:aggregate

It will need to be automatically merged into the gh-pages branch, but that is as simple as this:

$ git checkout master
$ mvn javadoc:aggregate
$ git checkout gh-pages
$ mv target/site/apidocs/ ./
$ git status
$ # Amend the branch as necessary.
$ git commit
$ git push

There is a Maven plugin to perform this work, but it is broken. The javadoc:aggregate step will emit documentation into target/site/apidocs. The reason that we use this aggregate step instead of bare javadoc is that we want one comprehensive Javadoc emission that includes all Maven submodules versus trying to manually concatenate this together.

Output documentation lives in the Java Client Github Project Page.

Contact

• All of the core developers are accessible via the Prometheus Developers Mailinglist.