✔️ tally

Fast, buffered, hierarchical stats collection in Java. Go here for the Go client.

Abstract

Tally provides a common interface for emitting metrics, while letting you not worry about the velocity of metrics emission.

By default it buffers counters, gauges and histograms at a specified interval but does not buffer timer values. This is primarily so timer values can have all their values sampled if desired and if not they can be sampled as summaries or histograms independently by a reporter.

Structure

Scope: Keeps track of metrics, and their common metadata.
Metrics: Counters, Gauges, Timers and Histograms.
Reporter: Implemented by you. Accepts aggregated values from the scope. Forwards the aggregated values to your metrics ingestion pipeline.

Acquire a Scope

// Implement as you will
StatsReporter reporter = new MyStatsReporter();

Map<String, String> tags = new HashMap<>(2, 1);
tags.put("dc", "east-1");
tags.put("type", "master");

Scope scope = new RootScopeBuilder()
    .reporter(reporter)
    .tags(tags)
    .reportEvery(Duration.ofSeconds(1))

Get/Create a metric; use it

Counter reqCounter = scope.counter("requests");
reqCounter.inc(1);

Gauge queueGauge = scope.gauge("queue_length");
queueGauge.update(42);

Report your metrics

Use one of the inbuilt reporters or implement your own using the StatsReporter interface.

Example Usage

Run the example by running:

$ ./gradlew run

This runs the PrintStatsReporterExample class in the tally-example project.

Artifacts Published

All artifacts are published under the group com.uber.m3.

tally-m3: The tally M3 reporter
tally-statsd: The tally StatsD reporter
tally-core: tally core functionality that includes interfaces and utilities to report metrics to M3
tally-example: Example usages with different reporters

Versioning

We follow semantic versioning outlined here. In summary, given a version of MAJOR.MINOR.PATCH (e.g. 1.2.0):

MAJOR version changes are breaking changes to the public API
MINOR version changes are backwards-compatible changes that include new functionality
PATCH version changes are backwards-compatible bug fixes

Released under the MIT License.

longquanzheng / tally