<commit_before>kamon-prometheus
================

A Kamon extension that creates a Spray endpoint which Prometheus can use to scrape the metrics generated by Kamon.

_A work in progress…_

Building
--------

Uses sbt, but you will need to have Google’s protocol buffers compiler `protoc` on your path.  On OS X, you should be
able to just `brew install protobuf`.

Development
-----------

=== Adding support for a new Kamon category

To add support to support a new Kamon category, follow these steps:

1. Add a new factory method to link:src/main/scala/com/monsanto/arch/kamon/prometheus/metric/Metric.scala[`Metric`] that
   will generate the new metric.  Be sure to set the `KamonCategory` label appropriately.
2. In link:src/main/scala/com/monsanto/arch/kamon/prometheus/converter/SnapshotConverter.scala[`SnapshotConverter`],
   ensure that the `apply` method will appropriately handle the new category type.
3. Add necessary tests to link:src/test/scala/com/monsanto/arch/kamon/prometheus/converter/SnapshotConverterSpec.scala[`SnapshotConverterSpec`].
   Be sure to test for name munging, help support, etc.
4. Create a new serialisation fixture (see
   link:src/test/scala/com/monsanto/arch/kamon/prometheus/metric/CounterSerialisationFixture.scala[`CounterSerialisationFixture`])
   for the category.
5. Use the serialisation fixture in the tests for each format (currently
   link:src/test/scala/com/monsanto/arch/kamon/prometheus/metric/TextFormatSpec.scala[`TextFormatSpec`] and
   link:src/test/scala/com/monsanto/arch/kamon/prometheus/metric/ProtoBufFormatSpec.scala[`TextFormatSpec`]).
6. Add a generator for metric families of the new category to
   link:src/test/scala/com/monsanto/arch/kamon/prometheus/PrometheusGen.scala[`PrometheusGen`].  Be sure that the
   `snapshot` generator

TODO
----

For initial release:

* Metric types:
** Counters
** Gauges
** Histograms
** Min-max counters
** Traces and trace segments
* Output via endpoint supporting:
** Text representation
** Protocol buffer representation

Further development:

* Support configuration-supplied metric name prefix
* Support getting help strings from tags (configuration-defined)
* Support doing something with units of measurement available within Kamon

Even further out:

* Alternative human-friendly formats<commit_msg>Add a real README<commit_after>kamon-prometheus
================

This library provides a Kamon module that can serve metrics to
http://prometheus.io/[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 a Spray route that your
application can use to serve metrics to Prometheus.

Features
--------

* 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 a Spray route that supports:
** Both text and https://developers.google.com/protocol-buffers/[Protocol
   buffer] representation formats
** Optional gzip compression
* Allows configuration of:
** Refresh interval to match Prometheus
** Metric subscriptions to export
** Additional Prometheus labels on exported metrics



Installation
------------

In order to use this module, you will need to add the following dependency to
your `build.sbt`:

[source,scala]
------------------------------------------------------------------------------
libraryDependencies += "com.monsanto.arch" %% "kamon-prometheus" % "0.1.3"
------------------------------------------------------------------------------

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 <<Usage,include the extension’s Spray route somewhere in your service>> so
that Prometheus can invoke it.


Dependencies
------------

This module depends on:

* http://akka.io[Akka actors]
* http://kamon.io[Kamon core]
* http://spray.io/[Spray routing]
* https://github.com/typesafehub/config[Typesafe config]
* https://developers.google.com/protocol-buffers/[Protocol buffers for Java]
* https://github.com/scala/scala-parser-combinators[Scala parser combinators] _(optional)_

Additional dependencies are required if you are interested in
<<building,building the library>>.


Configuration
-------------

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`.

=== Refresh interval

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.

=== Subscriptions

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:


[source,scala]
.The default _kamon-prometheus_ subscriptions
------------------------------------------------------------------------------
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 = [ "**" ]
  }
------------------------------------------------------------------------------


=== Additional labels

_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 empt by
default.

For example, given:

[source,scala]
.The default _kamon-prometheus_ subscriptions
------------------------------------------------------------------------------
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
http://prometheus.io/docs/concepts/data_model/#metric-names-and-labels[Prometheus’ naming requirements].


Usage
-----

The module provides a Spray route which you can access via
`Kamon(Prometheus).route`.  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`:

[source,scala]
.A minimal application
------------------------------------------------------------------------------
import akka.actor.ActorSystem
import com.monsanto.arch.kamon.prometheus.Prometheus
import kamon.Kamon
import spray.routing.SimpleRoutingApp

object Main extends App with SimpleRoutingApp {
  Kamon.start()

  implicit val actorSystem = ActorSystem()

  startServer("localhost", 8888) {
    path("metrics") {
      Kamon(Prometheus).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).


Development
-----------

[[building]]
=== Building the library

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
https://developers.google.com/protocol-buffers/docs/downloads[download]
Protocol buffers directly from Google.  However, there may be simpler options.
For example, on OS X, you can use http://brew.sh[homebrew] and just `brew
install protobuf`.

Additionally, to build the demo, you will need to have Docker set up.


=== Contributing to the project

Outside contributions to this project are welcome!  Please review
link:CONTRIBUTING.md[] for more information.


Future plans
------------

Check out the https://github.com/MonsantoCo/kamon-prometheus/issues[issues]
page.  Please star issues that are important to you.
{'fraction_non_alphanumeric': 0.16155162578436966, 'fraction_numerical': 0.002738163148887621, 'mean_word_length': 2.9629294755877034, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5954636', 'n_tokens_mistral': 2366, 'n_tokens_neox': 2232, 'n_words': 864}