JarCastingYammer Extra
Extension for clients migrating from Yammer that allows migration to our client library while retaining publication to Yammer.
Instrumenting Your Yammer Application
Add Dependency
Determine the latest version of the Yammer extra in Maven Central.
Maven
Add a dependency to your pom:
<dependency>
<groupId>com.arpnetworking.metrics.extras</groupId>
<artifactId>yammer-extra</artifactId>
<version>VERSION</version>
</dependency>
Add the Maven Central repository either to your ~/.m2/settings.xml or into your project's pom. Alternatively, if using the local version no changes are necessary as the local repository is enabled by default.
Gradle
Add a dependency to your build.gradle:
compile group: 'com.arpnetworking.metrics.extras', name: 'yammer-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" % "yammer-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 to Yammer
When your application instantiates the MetricsFactory you should also supply an instance of YammerMetricsSink as part of the sinks collection. For example:
final MetricsFactory metricsFactory = new MetricsFactory.Builder()
.setCluster("MyCluster")
.setService("MyService")
.setSinks(Arrays.asList(
new TsdQueryLogSink.Builder()
.setPath("/var/logs")
.setName("myapp-query")
.build(),
// Additional Yammer Sink:
new YammerMetricsSink.Builder()
.setMetricsRegistry(metricsRegistry)
.build()));
.build();
The Yammer MetricsRegistry on YammerMetricsSink.Builder is optional and defaults to Metrics.defaultRegistry() if not set (or set to null).
Publishing via Yammer
This extra package contains classes that can be used to supplement Yammer output. The first way this can be done is to use the yammer-extra package and record all metrics against a MetricsRgistry in the com.arpnetworking.metrics.yammer package. This will allow existing code written against the Yammer metrics interfaces to work 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 MetricsRegistry registry = new com.arpnetworking.metrics.yammer.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 yammer-replace library that serves as a full replacement for Yammer metrics. This is recommended for times when it is not possible to modify existing code that uses Yammer metrics. To use this method, remove the metrics-core.jar from the classpath of the target application and add yammer-replace.jar in its place. All use of Yammer 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_YAMMER_EXTRA_CLUSTER - The name of the cluster that the running instance belong to.
- METRICS_YAMMER_EXTRA_SERVICE - The name of the service that the running instance is reporting for.
- METRICS_YAMMER_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_YAMMER_EXTRA_CLUSTER - YammerCluster
- METRICS_YAMMER_EXTRA_SERVICE - YammerService
- METRICS_YAMMER_EXTRA_DIRECTORY - /tmp
Differences
Yammer metrics provides some interfaces that ArpNetworking metrics does not. For instance, there is no Meter in ArpNetworking metrics, and counters act differently in Yammer than here. This section will detail the differences.
Counter
Both Yammer 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 Yammer'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 Yammer metric will be in the 'sum' statistic's value.
Timer
Timers in Yammer 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 Yammer 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 Yammer metrics produces due to the retention of samples.
Histograms
Histograms exist in Yammer 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 Yammer histograms provide.
Building
Prerequisites:
Building:
metrics-yammer-extra> ./mvnw package
To use the local version you must first install it locally:
metrics-yammer-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