Easy to use Java stopwatch allowing measurement of elapsed time.
- 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
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);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
} ]
}<dependency>
<groupId>com.ethlo.time</groupId>
<artifactId>chronograph</artifactId>
<version>5.1.0</version>
</dependency>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"));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());You can choose to output the results using different styles and colors. Below are a few examples.
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());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:
- https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/System.html#nanoTime()
- https://shipilev.net/blog/2014/nanotrusting-nanotime/#_timers
The Chronograph is NOT thread safe.



