Client library for collecting metrics.
Java Other
Latest commit 54dfcba Feb 20, 2017 @brharrington brharrington committed on GitHub always increment count for recorded values (#376)
The Atlas registry was only incrementing the timer and
distribution summary objects if the recorded amount was
positive. If the amount was zero or negative it was

Negative latency values are sometimes seen due to clock
adjustments on a machine. Also really quick events that
call `System.currentTimeMillis` for getting the time can
get a latency of 0. These should be reflected in the count
statistic for the timer or else it causes confusion
because the number of events will not match what the user

With this change negative and 0 values will update the
count, but not other statistics.
Failed to load latest commit information.
codequality add map for storing arbitrary state with registry Feb 10, 2017
docs refer to version 0.51.0 in docs (#375) Feb 10, 2017
gradle/wrapper update to gradle 3.0 and nebula 3.4.0 (#314) Aug 20, 2016
scripts update gh-pages helper script Apr 14, 2016
spectator-agent zero metrics from snapshot if no change in count (#366) Feb 2, 2017
spectator-api A counter that keeps track of its last update (#374) Feb 10, 2017
spectator-ext-aws use compile scope for deps in public api (#316) Sep 1, 2016
spectator-ext-gc use compile scope for deps in public api (#316) Sep 1, 2016
spectator-ext-jvm use compile scope for deps in public api (#316) Sep 1, 2016
spectator-ext-log4j2 use compile scope for deps in public api (#316) Sep 1, 2016
spectator-ext-placeholders add MdcTagFactory (#328) Oct 12, 2016
spectator-ext-sandbox allow uri to be specified as string (#371) Feb 9, 2017
spectator-ext-spark Update spectator-ext-spark (#365) Feb 2, 2017
spectator-nflx-plugin cleanup dependencies (#340) Oct 28, 2016
spectator-nflx cleanup dependencies (#340) Oct 28, 2016
spectator-reg-atlas always increment count for recorded values (#376) Feb 20, 2017
spectator-reg-metrics3 make gauges more consistent with other basic types (#353) Dec 4, 2016
spectator-reg-servo fix CCE for reading gauges via ServoRegistry (#361) Jan 11, 2017
spectator-web-spring make gauges more consistent with other basic types (#353) Dec 4, 2016
.gitignore add wiki/site dir to .gitignore Apr 2, 2016
.netflixoss use jdk 1.8 Aug 6, 2015
.travis.yml Updated Bintray API key May 28, 2016 Need a for bintray automation Jan 23, 2015
LICENSE add license file Dec 4, 2014
OSSMETADATA adding OSSMETADATA for NetflixOSS tracking Dec 11, 2015 refer to version 0.51.0 in docs (#375) Feb 10, 2017
build.gradle ensure gauge polling stops if registry is reaped (#354) Dec 4, 2016 pass in credentials Aug 6, 2015 udpate dependency recommendations Oct 30, 2016
gradlew initial version Jul 18, 2014 add install script Aug 6, 2015
mkdocs.yml switch to material theme for mkdocs (#372) Feb 9, 2017
settings.gradle add agent that can be hooked to jvm (#324) Oct 7, 2016


Simple library for instrumenting code to record dimensional time series.


  • Java 8 or higher.
  • Java 7 or higher for spectator 0.27.x or earlier.



To instrument your code you need to depend on the api library. This provides the minimal interfaces for you to code against and build test cases. The only dependency is slf4j.

If running at Netflix with the standard platform, see the Netflix Integration page on the wiki.

Instrumenting Code

Suppose we have a server and we want to keep track of:

  • Number of requests received with dimensions for breaking down by status code, country, and the exception type if the request fails in an unexpected way.
  • Latency for handling requests.
  • Summary of the response sizes.
  • Current number of active connections on the server.

Here is some sample code that does that:

// In the application initialization setup a registry
Registry registry = new DefaultRegistry();
Server s = new Server(registry);

public class Server {
  private final Registry registry;
  private final Id requestCountId;
  private final Timer requestLatency;
  private final DistributionSummary responseSizes;

  public Server(Registry registry) {
    this.registry = registry;

    // Create a base id for the request count. The id will get refined with
    // additional dimensions when we receive a request.
    requestCountId = registry.createId("server.requestCount");

    // Create a timer for tracking the latency. The reference can be held onto
    // to avoid additional lookup cost in critical paths.
    requestLatency = registry.timer("server.requestLatency");

    // Create a distribution summary meter for tracking the response sizes.
    responseSizes = registry.distributionSummary("server.responseSizes");

    // Gauge type that can be sampled. In this case it will invoke the
    // specified method via reflection to get the value. The registry will
    // keep a weak reference to the object passed in so that registration will
    // not prevent garbage collection of the server object.
    registry.methodValue("server.numConnections", this, "getNumConnections");

  public Response handle(Request req) {
    final long s = System.nanoTime();
    requestLatency.record(() -> {
      try {
        Response res = doSomething(req);

        // Update the counter id with dimensions based on the request. The
        // counter will then be looked up in the registry which should be
        // fairly cheap, such as lookup of id object in a ConcurrentHashMap.
        // However, it is more expensive than having a local variable set
        // to the counter.
        final Id cntId = requestCountId
          .withTag("status", res.status());


        return res;
      } catch (Exception e) {
        final Id cntId = requestCountId
          .withTag("status", "exception")
          .withTag("error", e.getClass().getSimpleName());
        throw e;

  public int getNumConnections() {
    // however we determine the current number of connections on the server