Skip to content

Latest commit

 

History

History
77 lines (52 loc) · 2.91 KB

README.md

File metadata and controls

77 lines (52 loc) · 2.91 KB
Raw

Scientist4J

Maven Central Javadoc

A port of Github's refactoring tool Scientist in Java

Installation

<dependency>
    <groupId>com.github.rawls238</groupId>
    <artifactId>Scientist4JCore</artifactId>
    <version>0.7</version>
</dependency>

Usage

This Java port supports most of the functionality of the original Scientist library in Ruby, however its interface is a bit different.

The core component of this library is the Experiment<T> class. It's recommended to use this class as a Singleton. The main usage is as follows:

Basic Usage

You can either run a synchronous experiment or an asynchronous experiment.

For a synchronous experiment, the order in which control and candidate functions are run is randomized.

To run a synchronous experiment:

Experiment<Integer> e = new Experiment("foo");
e.run(this::controlFunction, this::candidateFunction);

For an asynchronous experiment, the two functions are run asynchronously.

To run an asynchronous experiment:

Experiment<Integer> e = new Experiment("foo");
e.runAsync(this::controlFunction, this::candidateFunction);

Behind the scenes the following occurs in both cases:

  • It decides whether or not to run the candidate function
  • Measures the durations of all behaviors
  • Compares the result of the two
  • Swallows (but records) any exceptions raised by the candidate
  • Publishes all this information.

Dropwizard

Out of the box this uses Dropwizard metrics to report the following stats. The following metrics are reported which have the form scientist.[experiment name].*:

  • duration of default behavior in ms
  • duration of candidate behavior in ms
  • counter of total number of users going through the codepath
  • counter of number of mismatches
  • counter of candidate exceptions

You can provide your own metric registry object/bean via the constructor or by extending the Experiment class and overriding the getMetrics method.

Optional Configuration

Users can optionally override the following functions:

  • publish (to publish results of an experiment if you don't want to use the default Dropwizard metrics)
  • compareResults (by default this library just uses equals between objects for equality, but in case you want to special case equality between objects)
  • enabled (to limit what % of users get exposed to the new code path - by default it's 100%)
  • runIf (to enforce conditional behavior on who should be exposed to the new code path)
  • isAsync (force using the async for legacy code or move to runAsync method)

License: MIT