Metrics-Scala

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

This is the Scala API for Coda Hale'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.

Contents

• Usage
• Manual
• Manual (version 2.x)
• Features
• Available versions
• Download
• Support
• License

Usage

Metrics-scala provides an easy way to create metrics and health checks in Scala. Metrics-core requires an application wide MetricRegistry. Create an Instrumented trait that refers to that registry and extends the InstrumentedBuilder trait.

object YourApplication {
  /** The application wide metrics registry. */
  val metricRegistry = new com.codahale.metrics.MetricRegistry()
}
trait Instrumented extends nl.grons.metrics.scala.InstrumentedBuilder {
  val metricRegistry = YourApplication.metricRegistry
}

Now you can create metrics by using the metrics metrics builder.

class Example(db: Database) extends Instrumented {
  private[this] val loading = metrics.timer("loading")

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

For more detailed information see the manual. For more information on Metrics-core 3.x, please see the documentation.

See the change log for API changes compared to the 2.x versions.

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 (Scala 2.10 or later only).
• Future support (Scala 2.10 or later only).

Available versions

Please consult the table below to see which versions of metrics-scala are available for which scala versions.

Note that only the versions 2.1.4 and 2.1.5 support OSGI.

Metrics- scala version	Metrics- core version	Akka- version	Scala version
			2.9.1	2.9.1-1	2.9.2	2.9.3	2.10.x	2.11.x
2.1.2	same		✓	✓	✓
2.1.3	same		✓	✓	✓
2.1.4	same		✓	✓	✓
2.1.5	same		✓	✓	✓		✓	✓
2.2.0	same		✓	✓	✓	✓	✓
3.0.0	same		✓	✓	✓	✓	✓
3.0.1	same	2.2.0 (*)	✓	✓	✓	✓	✓
3.0.2	3.0.1	2.2.0 (*)	✓	✓	✓	✓	✓
3.0.3	3.0.1	2.2.0 (*)	✓	✓	✓	✓	✓
3.0.3_a2.1.0	3.0.1	2.1.0					✓
3.0.4	3.0.1	2.2.0	✓	✓	✓	✓	✓
3.0.5	3.0.2		✓	✓	✓	✓
3.0.5_a2.1	3.0.2	2.1.4					✓
3.0.5_a2.2	3.0.2	2.2.4					✓
3.0.5_a2.3	3.0.2	2.3.0					✓
3.1.0	3.0.2		✓	✓	✓	✓	✓	✓
3.1.0_a2.1	3.0.2	2.1.4					✓
3.1.0_a2.2	3.0.2	2.2.4					✓
3.1.0_a2.3	3.0.2	2.3.2					✓	✓

If you need another version mix please open an issue, or sent an email to the metrics mailing list.

(*) Metrics-scala 3.0.1, 3.0.2 and 3.0.3 erroneously depend on Akka [2.2,). When Akka came with pre-releases of 2.3 this wont work (2.2 and 2.3 are not binary compatible). Either upgrade metrics-scala to at least 3.0.4 or fix the Akka dependency in your project to 2.2.0.

Note: It might be wise to use the latest minor-version of Akka. For example 2.1.4 instead of 2.1.0, 2.2.4 instead of 2.2.0, and 2.3.2 instead of 2.3.0. To do this you can fix the Akka version in your project's build configuration.

Download

SBT:

libraryDependencies += "nl.grons" %% "metrics-scala" % "3.1.0_a2.3"

Maven:

<properties>
    <scala.version>2.11.0</scala.version>
    <scala.dep.version>2.11</scala.dep.version>
</properties>
<dependency>
    <groupId>nl.grons</groupId>
    <artifactId>metrics-scala_${scala.dep.version}</artifactId>
    <version>3.1.0_a2.3</version>
</dependency>

Note: For scala versions before 2.10, you need to use the full scala version in the artifact name; e.g. metrics-scala_2.9.1-1.

Note: If you depend on JMX: 2.2.0 has a small bug that makes it inconvenient to use JMX.

Note: If you are not using the latest version, make sure you read the notes on Akka above.

Support

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

License

Copyright (c) 2010-2012 Coda Hale, Yammer.com (before 3.0.0)

Copyright (c) 2013-2014 Erik van Oosten (3.0.0 and later)

Published under Apache Software License 2.0, see LICENSE