PerfMark

PerfMark Hummingbird

PerfMark is a low-overhead, manually-instrumented, tracing library for Java. Users can add the tracing function calls to their code to see how long each part takes.

Features

Usage

To use PerfMark, add the following dependencies to your build.gradle:

In your code, add the PerfMark tracing calls like so:

Map<String, Header> parseHeaders(List<String> rawHeaders) {
  PerfMark.startTask("Parse HTTP headers");
  try {
    Map<String, String> headers = new HashMap<>();
    for (String rawHeader : rawHeaders) {
      Header header = parseHeader(rawHeader);
      headers.put(header.name(), header);
    }
    return headers;
  } finally {
    PerfMark.stopTask("Parse HTTP headers");
  }
}

PerfMark can also be used to record asynchronous work:

Future<Response> buildResponse() {
  PerfMark.startTask("Build Response");
  final Link link = PerfMark.linkOut();
  try {
    return executor.submit(() -> {
      PerfMark.startTask("Async Response");
      PerfMark.linkIn(link);
      try {
        return new Response(/* ... */);
      } finally {
        PerfMark.stopTask("Async Response");
      }
    });
  } finally {
    PerfMark.stopTask("Build Response");
  }
}

To view the traces in your browser, generate the HTML:

  PerfMark.setEnabled(true);
  PerfMark.startTask("My Task");
  } finally {
    PerfMark.stopTask("My Task");
  }
  TraceEventViewer.writeTraceHtml();
}

The output looks like:

PerfMark Hummingbird

Versioning and API Stability

PerfMark uses Semantic Versioning, and thus will not break existing APIs within a minor version update. PerfMark may need to disable some functionality, and thus may need to make some tracing calls become No-ops. In such cases, it will remain safe to call these functions being recorded.

Users

PerfMark was designed originally for gRPC.