Client library for collecting metrics.
Java Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
codequality move expr eval to impl package, add tests (#387) Mar 24, 2017
docs update doc version to 0.62.0 (#527) Feb 23, 2018
gradle/wrapper update to gradle 4.8 (#567) Jun 5, 2018
scripts update gh-pages helper script Apr 14, 2016
spectator-agent delay resolving agent configs (#553) May 19, 2018
spectator-api do not force update of polled gauges inline (#562) May 30, 2018
spectator-ext-aws add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-ext-aws2 add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-ext-gc add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-ext-ipc use String variant for ServerGroup helper (#569) Jun 6, 2018
spectator-ext-jvm Add support for CompositeData values to JMX (#570) Jun 6, 2018
spectator-ext-log4j1 add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-ext-log4j2 add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-ext-placeholders allow counters to accept floating point delta (#547) May 8, 2018
spectator-ext-sandbox Helper method to specify the gzip compression level (#536) Apr 9, 2018
spectator-ext-spark add max gauge type to registry (#548) May 9, 2018
spectator-nflx-plugin use AtlasRegistry if atlas-client is new enough (#559) May 29, 2018
spectator-nflx update nflx plugin to use archaius2 (#525) Feb 23, 2018
spectator-perf add Automatic-Module-Name to manifest (#515) Jan 27, 2018
spectator-reg-atlas make removeExpiredMeters public for AtlasRegistry (#565) May 30, 2018
spectator-reg-metrics3 do not force update of polled gauges inline (#562) May 30, 2018
spectator-reg-servo fix illegal reflective access for ServoIdTest (#563) May 30, 2018
spectator-web-spring do not force update of polled gauges inline (#562) May 30, 2018
.gitignore add wiki/site dir to .gitignore Apr 2, 2016
.netflixoss use jdk 1.8 Aug 6, 2015
.travis.yml update to gradle 4.8 (#567) Jun 5, 2018
CHANGELOG.md Need a CHANGELOG.md for bintray automation Jan 23, 2015
CONTRIBUTING.md add contributing guide (#489) Oct 26, 2017
LICENSE add license file Dec 4, 2014
OSSMETADATA adding OSSMETADATA for NetflixOSS tracking Dec 11, 2015
README.md update doc version to 0.62.0 (#527) Feb 23, 2018
build.gradle nebula 5.1.0 (#568) Jun 5, 2018
buildViaTravis.sh only publish from jdk8 build (#437) Jul 31, 2017
dependencies.properties fix illegal reflective access for ServoIdTest (#563) May 30, 2018
gradlew update to gradle 4.8 (#567) Jun 5, 2018
installViaTravis.sh add install script Aug 6, 2015
mkdocs.yml docs: add section on `ThreadPoolMonitor` (#464) Sep 2, 2017
settings.gradle initial version of ipc extension (#540) Apr 28, 2018

README.md

Spectator

Simple library for instrumenting code to record dimensional time series.

Requirements

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

Documentation

Dependencies

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.

com.netflix.spectator:spectator-api:0.62.0

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;

  @Inject
  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("country", req.country())
          .withTag("status", res.status());
        registry.counter(cntId).increment();

        responseSizes.record(res.body().size());

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

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