Benchmarks

This document describes how to generate performance information about the bundle internals. Refer to the API page for more details.

Types of Benchmark Data

When initialized, this class registers a BenchmarkCollector service. This allows third party management bundles to get the performance measurements of bundles, using this utility.

Typically the BenchmarkUtil class is created in BundleActivator.start(BundleContext) method.

Developers must not forget to call the close() method when their bundle is stopped.

There are two types of benchmark related data supported by this utility:

• Benchmarks – typically used for measuring performance of a method or code block. The benchmarks are generated by begin(String event), begin(String event, long timeStamp), end(String event), end(String event, long timeStamp) methods.
• Measurements – typically used like special log messages, that are related to measurements of device performance. Those messages are generated by measureNow(String module, String text) method.

To make a difference between the two types of benchmark consider this:

• Consider using begin(String event) and end(String event) to measure the whole time spent in your method.
• Benchmarks are repeating events. The data is collection of multiple executions. An average/min/max values of the spent time in the code block is computed.
• If the method is supposed to toggle a remotely connected switch, consider using measureNow(String module, String text) method to measure how long it took to perform the operation on that particular device.

Using Benchmarks

Since measureNow(String module, String text) is more like a performance-related log message, there are some limitation and recommendation of using the benchmarks. Here is the correct way of using them:

BenchmarkUtil bench = ...;

  void myMethod() throws SomeException {
    bench.begin("myMethod");
    try {
      ... do something here, it might throw exception
    } finally {
      // ensure that if any kind of exception/error is thrown you will still
      // capture the end time of this benchmark entry
      bench.end("myMethod");
    }
  }

The above code ensures that the end(String event) method is always called to close the marker started with begin(String event). Using benchmarks is not limited only on methods, you can use it also on blocks:

  void start(BundleContext) {
    bench.begin("BundleActivator.start");

    bench.begin("BundleActivator.init");
    ... read your own configuration or initial setup
    bench.end("BundleActivator.init");

    bench.begin("BundleActivator.initTrackers");
    ... here you create some service trackers to get the services your need
    bench.end("BundleActivator.initTrackers");

    bench.begin("BundleActivator.registerServices");
    ... register the services you provide
    bench.end("BundleActivator.registerServices");

    bench.end("BundleActivator.start");
  }