This library provides a Kamon module that can serve metrics to Prometheus, an open source service monitoring system and time series database. Since Prometheus uses a scraping mechanism and its own data model, this module bridges the gap between the two. It converts Kamon metrics into a Prometheus-friendly format and provides integrations for both Spray and Akka HTTP so that your application can serve metrics to Prometheus.
-
Converts Kamon metrics data to conform to Prometheus’ data model, including:
-
Reasonably handles all Kamon entities, including custom entities
-
Preservation of units of measurement
-
-
Provides Spray and Akka HTTP route that supports:
-
Both text and Protocol buffer representation formats
-
Optional gzip compression
-
-
Allows collection of snapshots without an endpoint using an actor
-
Allows configuration of:
-
Refresh interval to match Prometheus
-
Metric subscriptions to export
-
Additional Prometheus labels on exported metrics
-
In order to use this module, you will need to add the following dependency to
your build.sbt
:
libraryDependencies += "com.monsanto.arch" %% "kamon-prometheus" % "0.2.0"
You may also need to add JCenter as a resolver:
resolvers += Resolver.jcenterRepo
Kamon’s module loader should automatically detect the presence of kamon-prometheus and start it. However, in order to be useful, you will need to include the extension’s Spray or Akka HTTP routes somewhere in your service so that Prometheus can invoke it.
This module depends on:
-
Akka HTTP (optional)
-
Spray routing (optional)
-
Scala parser combinators (optional)
Additional dependencies are required if you are interested in building the library.
You can configure the module much like any other Kamon module, by modifying
your application.conf
. All of the configuration entries for
kamon-prometheus are placed under kamon.prometheus
.
The kamon.prometheus.refresh-interval
setting determines how often the
kamon-prometheus will flush and serve new data. This setting must be at
least as large as kamon.metric.tick-interval
, and should match Prometheus’
scrape_interval
. The default refresh interval is one minute, which matches
Prometheus’ default.
Like most other Kamon reporting module, kamon-prometheus allows you to configure the metric categories to which the module will subscribe. By default, the following subscriptions are included:
kamon.prometheus {
subscriptions {
histogram = [ "**" ]
min-max-counter = [ "**" ]
gauge = [ "**" ]
counter = [ "**" ]
trace = [ "**" ]
trace-segment = [ "**" ]
akka-actor = [ "**" ]
akka-dispatcher = [ "**" ]
akka-router = [ "**" ]
system-metric = [ "**" ]
http-server = [ "**" ]
spray-can-server = [ "**" ]
}
kamon-prometheus will automatically add a metric’s tags, name, and category
to a published metric as labels. If you which to add additional labels, you
can add them under the kamon.prometheus.labels
path, which is empty by
default.
For example, given:
kamon.prometheus {
labels {
application_name = "my cool app"
application_version = "42"
}
}
All metrics published by kamon-prometheus will add the labels
application_name="my cool app"
and application_version="42"
to all
published metrics. Keep in mind that label names may munged to fit
Prometheus’ naming requirements.
There are currently three principal ways to use kamon-prometheus:
-
Using the Spray endpoint
-
Using the Akka HTTP endpoint
-
Collecting metrics via an Actor
Once you have made the metrics available, you will need to configure Prometheus to scrape your application.
The module provides a Spray route which you can access via
SprayEndpoint(system).route
where system
is an actor system. You can
place this route anywhere in your application, but keep in mind that Prometheus
scrapes /metrics
by default. The following is the code for a minimal
application that will serve metrics from http://localhost:8888/metrics
:
import akka.actor.ActorSystem
import com.monsanto.arch.kamon.prometheus.spray.SprayEndpoint
import spray.routing.SimpleRoutingApp
object Main extends App with SimpleRoutingApp {
implicit val actorSystem = ActorSystem()
startServer("localhost", 8888) {
path("metrics") {
SprayEndpoint(actorSystem).route
}
}
}
Note that the route will only respond to GET
requests and will automatically
handle compression and media type negotiation. If there is no content yet
(generally before the first set of metrics has been collected), the route will
return a No Content response (204).
Using the Akka HTTP endpoint is just like using the Spray endpoint above, except that you use a different Akka extension.
import akka.actor.ActorSystem
import com.monsanto.arch.kamon.prometheus.spray.SprayEndpoint
import spray.routing.SimpleRoutingApp
object Main extends App with SimpleRoutingApp {
implicit val actorSystem = ActorSystem("Demo")
startServer("localhost", 8888) {
path("metrics") {
SprayEndpoint(actorSystem).route
}
}
}
For this functionality, please consult the documentation for PrometheusExtension.
Finally, all you need to do is configure a scrape configuration in Prometheus. The following snippet is a minimal example that shold work with the minimal server from the previous section.
scrape_configs:
- job_name: example
target_groups:
- targets: ['localhost:8888']
Note that the above configuration uses the default scrape_interval
(one
minute, matching kamon-prometheus’ default.) and metrics_path
(/metrics
).
You can use sbt
to build the library, but you will need to have Google’s
protocol buffers compiler protoc
on your path. You can
download
Protocol buffers directly from Google. However, there may be simpler options.
For example, on OS X, you can use homebrew and just brew
install protobuf
.
Additionally, to build the demo, you will need to have Docker set up.
Outside contributions to this project are welcome! Please review CONTRIBUTING.md for more information.
Check out the issues page. Please star issues that are important to you.