Skip to content

About

Java stopwatch for measuring elapsed time, with nested tasks and statistics (percentiles, std dev) and table output.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

135 Commits

Folders and files

Repository files navigation

Chronograph

Maven Central javadoc Codacy Badge License

Easy to use Java stopwatch allowing measurement of elapsed time.

Features

  • New in 4.0: Hierarchical task tracking - Start several nested tasks.
  • The same task can be timed multiple times for aggregated/cumulative data.
  • Supports numerous metrics:
    • average
    • median
    • min/max
    • standard deviation
    • percentiles
    • percentage
    • count
    • total time
  • Human-readable durations
  • Well documented
  • Highly tweaked code for minimal overhead.
  • Dynamic ASCII/Unicode table support for detailed result output on the console or in logs with support for colored output (ANSI console)
  • Easy to fetch the underlying data for when you need your own output format, like JSON
  • Configurable sample interval for very short running tasks
  • No dependencies

Sample usage

hierarchicalTasks source

Tasks can be nested. Time spent in a task that is not covered by its subtasks is reported as <overhead>.

final Chronograph c = Chronograph.create();
c.time("Request", () ->
{
    for (int i = 0; i < 13; i++)
    {
        c.time("Fetch", () -> busy(12));
    }

    // Overhead
    busy(300);

    c.time("De-serialize", () ->
    {
        // Overhead
        busy(14);
        c.time("JSON de-serialize", () -> busy(44));
    });
});

System.out.println(c);

startAndStop source

Start and stop a task explicitly. Printing the chronograph renders the results as a table.

final Chronograph chronograph = Chronograph.create();
chronograph.start("my-task");
// perform a task
chronograph.stop();
System.out.println(chronograph);

assertEquals(1, chronograph.getTask("my-task").getInvocations());

timeLambda source

Time a lambda. The overloads of time cover the functional interfaces in java.util.function, so a return value is passed through.

final List<Long> myList = new ArrayList<>(Arrays.asList(5L, 3L, 9L, 1L));
final Chronograph chronograph = Chronograph.create();
chronograph.time("List sort", () -> myList.sort(Comparator.naturalOrder()));
final Long max = chronograph.time("Find max", () -> myList.get(myList.size() - 1));
System.out.println(chronograph);

assertEquals(9L, max);

Sample output in tables: Table output

Or in JSON format if you need it for later analysis:

{
  "tasks" : [ {
    "name" : "Request",
    "subtasks" : [ {
      "name" : "Fetch",
      "total_time" : "0.15757311",
      "subtasks_time" : "0",
      "self_time" : "0.15757311",
      "invocation_count" : 13,
      "statistics" : {
        "average" : "0.012121008",
        "median" : "0.012110195",
        "min" : "0.01208667",
        "max" : "0.012215087",
        "standard_deviation" : "0.000038184",
        "percentiles" : {
          "75.0" : "0.012130908",
          "90.0" : "0.012183143",
          "95.0" : "0.012215087",
          "99.0" : "0.012215087",
          "99.9" : "0.012215087"
        }
      }
    }, {
      "name" : "De-serialize",
      "subtasks" : [ {
        "name" : "JSON de-serialize",
        "total_time" : "0.044214251",
        "subtasks_time" : "0",
        "self_time" : "0.044214251",
        "invocation_count" : 1
      }, {
        "name" : "<overhead>",
        "total_time" : "0.015809396",
        "subtasks_time" : "0",
        "self_time" : "0.015809396",
        "invocation_count" : 1
      } ],
      "total_time" : "0.060023647",
      "subtasks_time" : "0.060023647",
      "self_time" : "0",
      "invocation_count" : 1
    }, {
      "name" : "<overhead>",
      "total_time" : "0.301883674",
      "subtasks_time" : "0",
      "self_time" : "0.301883674",
      "invocation_count" : 1
    } ],
    "total_time" : "0.519480431",
    "subtasks_time" : "0.519480431",
    "self_time" : "0",
    "invocation_count" : 1
  }, {
    "name" : "Response",
    "subtasks" : [ {
      "name" : "Logging",
      "total_time" : "0.011222603",
      "subtasks_time" : "0",
      "self_time" : "0.011222603",
      "invocation_count" : 1
    }, {
      "name" : "Serialize",
      "subtasks" : [ {
        "name" : "JSON serialize",
        "total_time" : "0.027233243",
        "subtasks_time" : "0",
        "self_time" : "0.027233243",
        "invocation_count" : 1
      }, {
        "name" : "<overhead>",
        "total_time" : "0.014704076",
        "subtasks_time" : "0",
        "self_time" : "0.014704076",
        "invocation_count" : 1
      } ],
      "total_time" : "0.041937319",
      "subtasks_time" : "0.041937319",
      "self_time" : "0",
      "invocation_count" : 1
    } ],
    "total_time" : "0.053987607",
    "subtasks_time" : "0.053159922",
    "self_time" : "0.000827685",
    "invocation_count" : 1
  } ]
}

Getting started

Include in your project

Maven coordinates

<dependency>
  <groupId>com.ethlo.time</groupId>
  <artifactId>chronograph</artifactId>
  <version>5.1.0</version>
</dependency>

Choice of output columns

Empty columns will be dropped automatically. Included columns can be configured.

outputConfigFromScratch source

Begin from scratch and enable only the columns you want.

final OutputConfig outputConfig = new OutputConfig()
        .median(true)
        .standardDeviation(true);

assertTrue(outputConfig.median());

outputConfigFromDefault source

Begin from one of the predefined configurations, DEFAULT, COMPACT or EXTENDED, and adjust it. Each call returns a new configuration.

final OutputConfig outputConfig = OutputConfig.DEFAULT
        .percentiles(75, 90, 99, 99.9, 99.99);

assertEquals(5, outputConfig.percentiles().length);

formatAsTable source

Render the results as a table with a theme from TableThemes and your output configuration.

final Chronograph chronograph = Chronograph.create();
chronograph.time("my-task", () -> Math.sqrt(42));

final OutputConfig outputConfig = OutputConfig.EXTENDED;
final String table = new TableOutputFormatter(TableThemes.RED_HERRING, outputConfig)
        .format(chronograph.getTaskData());
System.out.println(table);

assertTrue(table.contains("my-task"));

Reduced sample interval

If you run very quick tasks (typically less than milliseconds) in a loop, it may be beneficial to not capture every iteration, but instead sample some of them.

minInterval source

Only capture an invocation when at least minInterval has passed since the last captured one. All invocations are still counted.

final Chronograph chronograph = Chronograph
        .create(CaptureConfig
                .minInterval(Duration.ofNanos(10_000))); // 10 microseconds

for (int i = 0; i < 100_000; i++)
{
    chronograph.time("quick-task", () -> Math.sqrt(42));
}

assertEquals(100_000, chronograph.getTask("quick-task").getInvocations());

Themes

You can choose to output the results using different styles and colors. Below are a few examples.

Themes Themes Themes Themes

customTheme source

Build a theme from scratch.

final TableTheme myTheme = TableTheme.builder()
        .stringColor(AnsiColor.BLUE)
        .numericColor(AnsiColor.GREEN)
        .horizontalSeparator(" ")
        .verticalSpacerColor(AnsiColor.GRAY)
        .horizontalSpacerColor(AnsiColor.GRAY)
        .build();

final Chronograph chronograph = Chronograph.create();
chronograph.time("my-task", () -> Math.sqrt(42));
System.out.println(new TableOutputFormatter(myTheme, OutputConfig.DEFAULT).format(chronograph.getTaskData()));

assertEquals(AnsiColor.BLUE, myTheme.getStringColor());

adjustTheme source

Or start from a predefined theme and change what you need.

final TableTheme myTheme = TableThemes.ROUNDED.begin()
        .stringColor(AnsiColor.YELLOW)
        .build();

assertEquals(AnsiColor.YELLOW, myTheme.getStringColor());

Limitations

Time resolution

This project is utilizing System.nanoTime() which has some inherent issues with very quick task times. It does have a nanosecond resolution, but not a nanosecond precision. These are still usually orders of magnitude away from what you are trying to measure, so it is not a problem. If you are micro-benchmarking, consider using a framework like JMH.

If you would like to know more:

Thread safety

The Chronograph is NOT thread safe.

About

Java stopwatch for measuring elapsed time, with nested tasks and statistics (percentiles, std dev) and table output.

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages