dikang123 / metrics-reporter-config

Description

Coda Hale's Metrics package makes it easy to create useful metrics so you know what is going on in production. In addition to showing up in the normal Java places (JMX), Metrics supports an arbitrary number of Reporters (where to send the application telemetry to make pretty graphs). Ganglia and Graphite (or both!) are among the most popular choices.

However, Metrics purposefully doesn't come with a kitchen sink of support for every dependency injection or configuration tool yet devised by Java developers. Metrics-Reporter-Config aims to provide a simple way to configure and enable a set of Reporters that can be shared among applications. It should fit most (say 90% of) use cases and avoid situations like a plethora of subtly incompatible properties files.

In particular, it should seamlessly fit into Dropwizard service Configuration classes.

Use

Maven

<dependency>
  <groupId>com.addthis.metrics</groupId>
  <artifactId>reporter-config</artifactId>
  <version>2.0.5</version>
</dependency>

Basics

Current supported reporters include:

• console
• csv
• ganglia
• graphite

Note that Metrics-Reporter-Config's dependencies on non-core reporters are optional in maven-speak. That means that depending on Metrics-Reporter-Config should not pull in "a bunch of junk", but your applications will need to explicitly depend on the reporters they want (such as metrics-ganglia).

An example config file might look like this:

csv:
  -
    outdir: '/tmp/metrics/crazy-debugging'
    period: 2
    timeunit: 'MINUTES'
ganglia:
  -
    period: 60
    timeunit: 'SECONDS'
    hosts:
      - host: 'gmond.domain.local'
        port: 8649
      - host: 'gmond-backup.domain.local'
        port: 8649
graphite:
  -
    period: 120
    timeunit: 'SECONDS'
    hosts:
     - host: 'graphite-server.domain.local'
        port: 2003

And then to wire up your app call ReporterConfig.loadFromFileAndValidate() (or loadFromFile() if you aren't into validating), and then enableAll().

In addition to an inline list, the ganglia config supports gmondConf field which tells it where to find gmond's config file (ie /etc/ganglia/gmond.conf) and read any UDP send channels there. This should make it easy to keep the java app config and the rest of the system in sync.

Dropwizard

Just add a ReporterConfig instance to your app's Configuration class. Metrics-Reporter-Config uses the same validation implementation as dropwizard. You will still need to call an enable method when initialization your app.

Predicates

predicate:
  color: "black"
  patterns:
    - ".*JMXONLY$"

Each reporter can have a simple name based predicate with a white or black list of regular expressions. Use this for rarely used metrics that will only show up in JMX without flooding ganglia with 20k extra metrics. In practice our configurations tend to look like this:

ganglia:
  -
    period: 60
    timeunit: 'SECONDS'
    gmondConf: '/etc/ganglia/gmond.conf'
    predicate:
      color: "black"
      patterns:
      - ".*JMXONLY$"

By default predicates operate on the "Metric Name" (usually something like MyClass). If you want to operable on the conventional "full" name (org.example.foo.MyClass) enable useQualifiedName.

[EXPERIMENTAL] If you want to report only a subset of the measurements that are reported by a meter then use can use the measurement options on the predicate configuration. This feature is only available if you include as a dependency a fork of the metrics project that supports this feature, such as http://github.com/mspiegel/metrics. If the per measurement filtering is available then it is only applied once a metric has passed the top level filter.

ganglia:
  -
    period: 60
    timeunit: 'SECONDS'
    gmondConf: '/etc/ganglia/gmond.conf'
    predicate:
      color: "black"
      patterns:
      - ".*JMXONLY$"
      histogram:
          color: "white"
          patterns:
          - metric: ".*WidgetRunner$"
            measure: "mean|stddev"
          - metric: ".*SprocketRunner$"
            measure: ".*percentile"

Graphite and Ganglia

The Graphite and Ganglia reporters supports the "prefix" parameter. Its value will be prepended to each metric name sent by reporter. This feature is only available in Ganglia if you include as a dependency a fork of the metrics project that supports this feature, such as http://github.com/mspiegel/metrics. This value may contain one of the following variable references using "${variable.name}" as format.

- host.name = the value returned for local host by `java.net.InetAddress#getHostAddress()`
- host.name.short = same as ${host.name} up to first dot
- host.address = the value returned for local host by `java.net.InetAddress#getHostName()`
- host.fqdn = the value returned for local host by `java.net.InetAddress#getCanonicalHostName()`

Each substituted value gets sanitized by replacing all characters that are not allowed in the host name plus "-" with the underscore. The Ganglia reporter additionally supports the "groupPrefix" parameter. This will add a prefix to the Ganglia metric group.

Building

Assuming you have Apache Maven installed and configured:

mvn package

And you should be all set.

To run individual tests use -Dtest= and -Dorg.slf4j.simpleLogger.defaultLogLevel= to change the test log level.

Administrivia

Versioning

It's x.y.z where:

• x: compatible Metrics major version
• y: next release
• z: bug fix only

License

Metrics-Reporter-Config is released under the Apache License Version 2.0. See Apache or the LICENSE file in this distribution for details.

Where People Hang Out

Main Metrics mailing list: http://groups.google.com/group/metrics-user