Metrics-Scala

Capturing JVM- and application-level metrics. So you know what's going on.

This is the Scala API for Dropwizard's Metrics library.

Initially this project started out as a line for line copy of the Metrics-scala module, released for multiple scala versions. Metrics dropped the scala module in version 3.0.0 and this project continued separately with the help of @scullxbones.

We strive for long term stability, correctness, an easy to use API and full documentation (in that order).

Usage
Manual
Manual (version 2.x)
Features
Available artifacts
Download
Support
License
Travis:

Usage

Metrics-scala provides an easy way to create metrics and health checks in Scala. Since version 3.5.5 creating metrics and health checks is as easy as extending DefaultInstrumented and using the metrics and healthCheck builders:

class Example(db: Database) extends nl.grons.metrics4.scala.DefaultInstrumented {
  // Define a health check
  healthCheck("alive") { workerThreadIsActive() }

  // Define a timer metric
  private[this] val loading = metrics.timer("loading")

  // Use timer metric
  def loadStuff(): Seq[Row] = loading.time {
    db.fetchRows()
  }
}

For more detailed information see the manual. For more information on Dropwizard-metrics 4.x, please see the documentation.

See also the change log for improvements and API changes.

Features

Easy creation of all metrics types.
Easy creation of Health Checks.
Almost invisible syntax for using timers (see example above).
Scala specific methods on metrics (e.g. += on counters).
Derives proper metrics names for Scala objects and closures.
Actor support.
Future support.
Hdrhistogram support.

Available artifacts (abbreviated)

The following artifacts are available:

metrics4-scala: adds a nice Scala API to Dropwizard Metrics
metrics4-akka: support for measuring Akka actors
metrics4-hdr: adds support for HdrHistogram to increase the accuracy of histograms

The table shows the available artifacts of metrics-scala. For the full list, including those targeting older Scala and Akka versions see all available versions.

Artifact name	Scala version		Akka version		Build against
Artifact name	2.11	2.12	2.4	2.5	Build against
metrics4-scala	✓	✓			Dropwizard-metrics 4.0.1
metrics4-akka_a24	✓	✓	✓	✓	Akka 2.4.20
metrics4-akka_a25		✓		✓	Akka 2.5.8
metrics4-scala-hdr	✓	✓			Hdr 1.1.0/2.1.9 (*)

(*) The first number is the version of "org.mpierce.metrics.reservoir" % "hdrhistogram-metrics-reservoir", the second the version of "org.hdrhistogram" % "HdrHistogram". See also hdrhistogram manual page.

Migrating from 3.x to 4.x

Migrating from 3.x to 4.x is simply a matter of replacing the package from nl.grons.metrics to nl.grons.metrics4, and recompiling the code.

Metrics-scala 3.x and metrics-scala 4.x can be used at the same time on top of either Dropwizard Metrics 3.x or 4.x (excluding Dropwizard metrics 4.0.0).

Download 4.x

Release notes for 4.0.1.

WARNING: "nl.grons" %% "metrics-scala" % "4.0.0" was accidentally released as well. Do not use it as it will give binary compatibility problems. Instead use "nl.grons" %% "metrics4-scala" % "4.0.1" as described below.

SBT:

libraryDependencies ++= Seq(
  "nl.grons" %% "metrics4-scala" % "4.0.1",
  "nl.grons" %% "metrics4-akka_a24" % "4.0.1",
  "nl.grons" %% "metrics4-scala-hdr" % "4.0.1"
)

Maven:

<properties>
    <scala.version>2.12.1</scala.version>
    <scala.compat.version>2.12</scala.compat.version>
    <metrics.scala.version>4.0.1</metrics.scala.version>
</properties>
<dependency>
    <groupId>nl.grons</groupId>
    <artifactId>metrics4-scala_${scala.compat.version}</artifactId>
    <version>${metrics.scala.version}</version>
</dependency>
<dependency>
    <groupId>nl.grons</groupId>
    <artifactId>metrics4-akka_a24_${scala.compat.version}</artifactId>
    <version>${metrics.scala.version}</version>
</dependency>
<dependency>
    <groupId>nl.grons</groupId>
    <artifactId>metrics4-scala-hdr_${scala.compat.version}</artifactId>
    <version>${metrics.scala.version}</version>
</dependency>

Download 2.x and 3.x

In the 2.x and 3.x versions you depend on a single artifact. Different versions target different Akka/Scala combinations. See all available versions to select the appropriate version.

Here are examples for metrics-scala 3.5.9 and Akka 2.4 (and Scala 2.12 in the Maven example):

SBT:

libraryDependencies += "nl.grons" %% "metrics-scala" % "3.5.9_a2.4"

Maven:

<properties>
    <scala.version>2.12.1</scala.version>
    <scala.compat.version>2.12</scala.compat.version>
</properties>
<dependency>
    <groupId>nl.grons</groupId>
    <artifactId>metrics-scala_${scala.compat.version}</artifactId>
    <version>3.5.9_a2.4</version>
</dependency>

To use hdrhistogram additional dependencies are needed. See the hdrhistogram manual page.

Dropwizard 5.x

Dropwizard metrics 5.x has been in RC state for some time now. Metrics-scala support for it can be found in the metrics5-dev branch. This will be released as soon as Dropwizard metrics and hdrhistogram have a non-RC 5.x release.

Support

If you find a bug, please open an issue, better yet: send a pull request. For questions, please sent an email to the metrics mailing list.

License

Published under Apache Software License 2.0, see LICENSE

filipochnik/metrics-scala