com.arpnetworking.metrics.extras:codahale-extra

Extension to metrics-java-client which adapts the client for use in conjunction or in place of the Codahale metrics library.

License

License

Categories

Categories

Net Metrics Application Testing & Monitoring Monitoring Networking
GroupId

GroupId

com.arpnetworking.metrics.extras
ArtifactId

ArtifactId

codahale-extra
Last Version

Last Version

0.7.0
Release Date

Release Date

Type

Type

jar
Description

Description

Extension to metrics-java-client which adapts the client for use in conjunction or in place of the Codahale metrics library.

Download codahale-extra

How to add to project

<!-- https://jarcasting.com/artifacts/com.arpnetworking.metrics.extras/codahale-extra/ -->
<dependency>
    <groupId>com.arpnetworking.metrics.extras</groupId>
    <artifactId>codahale-extra</artifactId>
    <version>0.7.0</version>
</dependency>
// https://jarcasting.com/artifacts/com.arpnetworking.metrics.extras/codahale-extra/
implementation 'com.arpnetworking.metrics.extras:codahale-extra:0.7.0'
// https://jarcasting.com/artifacts/com.arpnetworking.metrics.extras/codahale-extra/
implementation ("com.arpnetworking.metrics.extras:codahale-extra:0.7.0")
'com.arpnetworking.metrics.extras:codahale-extra:jar:0.7.0'
<dependency org="com.arpnetworking.metrics.extras" name="codahale-extra" rev="0.7.0">
  <artifact name="codahale-extra" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.arpnetworking.metrics.extras', module='codahale-extra', version='0.7.0')
)
libraryDependencies += "com.arpnetworking.metrics.extras" % "codahale-extra" % "0.7.0"
[com.arpnetworking.metrics.extras/codahale-extra "0.7.0"]

Dependencies

compile (4)

Group / Artifact Type Version
io.dropwizard.metrics : metrics-core jar 3.1.2
com.google.code.findbugs : findbugs-annotations jar 3.0.1
com.arpnetworking.metrics : metrics-client jar 0.7.0
com.arpnetworking.metrics.extras : file-sink-extra jar 0.7.0

provided (1)

Group / Artifact Type Version
com.arpnetworking.build : build-resources jar 1.0.6

test (3)

Group / Artifact Type Version
org.hamcrest : java-hamcrest jar 2.0.0.0
junit : junit jar 4.12
org.mockito : mockito-core jar 1.10.19

Project Modules

There are no modules declared in this project.

Codahale Extra

License: Apache 2 Travis Build Maven Artifact

Extension for clients migrating from Codahale metrics that allows migration to our client library while retaining publication to Codahale.

Instrumenting Your Codahale Application

Add Dependency

Determine the latest version of the Codahale extra in Maven Central.

Maven

Add a dependency to your pom:

<dependency>
    <groupId>com.arpnetworking.metrics.extras</groupId>
    <artifactId>codahale-extra</artifactId>
    <version>VERSION</version>
</dependency>

The Maven Central repository is included by default.

Gradle

Add a dependency to your build.gradle:

compile group: 'com.arpnetworking.metrics.extras', name: 'codahale-extra', version: 'VERSION'

Add at least one of the Maven Central Repository and/or Local Repository into build.gradle:

mavenCentral()
mavenLocal()

Play

Add a dependency to your project/Build.scala:

val appDependencies = Seq(
    ...
    "com.arpnetworking.metrics.extras" % "codahale-extra" % "VERSION"
    ...
)

The Maven Central repository is included by default. Alternatively, if using the local version add the local repository into project/plugins.sbt:

resolvers += Resolver.mavenLocal

Publishing via Codahale

This extra package contains classes that can be used to supplement Codahale output. The first way this can be done is to use the codahale-extra package and record all metrics against a MetricsRgistry in the com.arpnetworking.metrics.codahale package. This will allow existing code written against the Codahale metrics interfaces to work with ArpNetworking metrics, with the caveat that the use of static methods to create metrics is not supported. This is the preferred method of using this library.

final MetricsFactory metricsFactory = ...
final MetricsRegistry registry = new com.arpnetworking.metrics.codahale.MetricsFactory(metricsFactory);
Counter counter = registry.newCounter("foo");
counter.inc();

The other way to use this library is as a drop-in replacement. Through the use of shading we have created the codahale-replace library that serves as a full replacement for Codahale metrics. This is recommended for times when it is not possible to modify existing code that uses Codahale metrics. To use this method, remove the metrics-core.jar from the classpath of the target application and add codahale-replace.jar in its place. All use of Codahale metrics will instead be sent to Arpnetworking metrics (including all static references).

To configure the metrics library when employing a drop-in replacement you should set these environment variables:

  • METRICS_CODAHALE_EXTRA_CLUSTER - The name of the cluster that the running instance belong to.
  • METRICS_CODAHALE_EXTRA_SERVICE - The name of the service that the running instance is reporting for.
  • METRICS_CODAHALE_EXTRA_DIRECTORY - The directory to write the query log file to.

All the environment variables have defaults but it is highly recommended that the values be set to more appropriate values. The defaults are:

  • METRICS_CODAHALE_EXTRA_CLUSTER - CodahaleCluster
  • METRICS_CODAHALE_EXTRA_SERVICE - CodahaleService
  • METRICS_CODAHALE_EXTRA_DIRECTORY - /tmp

Differences

Codahale metrics provides some interfaces that ArpNetworking metrics does not. For instance, there is no Meter in ArpNetworking metrics, and counters act differently in Codahale than here. This section will detail the differences.

Counter

Both Codahale and ArpNetworking metrics contain counters that can be incremented by 1 or any arbitrary number. The difference is in ArpNetworking metrics' separation of units of work and tracking individual samples. This impedance mismatch is solved by storing each call to Codahale's counter inc as a separate sample in ArpNetworking metrics. This means that loops where inc() is called multiple times will translate to multiple samples of '1'. Normally this will not be a problem and the expected value of the Codahale metric will be in the 'sum' statistic's value. Note, however, that using Codahale metrics can lead to unintuitive sample distributions.

Timer

Timers in Codahale and ArpNetworking metrics are very similar. Their use is functionally equivalent. The only difference is in the reporting of values. Since ArpNetworking records individual samples, you will have access to statistically correct percentiles, min, max and counts.

Meter

Meters exist in Codahale to record rates. ArpNetworking metrics does not contain meters. All meters are converted into counters. Counters in ArpNetworking metrics allow for the computation of the rates that Codahale metrics produces due to the retention of samples.

Histograms

Histograms exist in Codahale to record percentiles. ArpNetworking metrics retains samples and uses histograms to store the samples. As a result, histograms are converted to counters and provide the same statistics as Codahale histograms provide.

Building

Prerequisites:

Building:

metrics-codahale-extra> ./mvnw package

To use the local version you must first install it locally:

metrics-codahale-extra> ./mvnw install

You can determine the version of the local build from the pom file. Using the local version is intended only for testing or development.

You may also need to add the local repository to your build in order to pick-up the local version:

  • Maven - Included by default.
  • Gradle - Add mavenLocal() to build.gradle in the repositories block.
  • SBT - Add resolvers += Resolver.mavenLocal into project/plugins.sbt.

License

Published under Apache Software License 2.0, see LICENSE

© Groupon Inc., 2014

Versions

Version
0.7.0
0.4.3
0.4.2
0.4.1
0.4.0
0.3.6