Skip to content
PerfMark is a High Performance Tracing Library.
Java Starlark
Branch: master
Clone or download

Latest commit

carl-mastrangelo all: add jdk8 and 14 builds
Added support for building an running with jdk14 and 8.   14 requires building with bytecode for java 7, so the target level must be raised for testing.  8 does not support building java 9 classes, so must be disabled.   These are mainly for testing.  Release will still be built with JDK 11, which supports both.
Latest commit 9fe7f12 Apr 5, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
agent all: add jdk8 and 14 builds Apr 5, 2020
api all: add jdk8 and 14 builds Apr 5, 2020
buildscripts update license Aug 13, 2019
doc update docs Jul 7, 2019
gradle/wrapper all: update to gradle 6.3 Apr 5, 2020
impl all: add jdk8 and 14 builds Apr 5, 2020
java6 all: add jdk8 and 14 builds Apr 5, 2020
java7 all: don't expose errorprone / jsr deps through POM Mar 30, 2020
java9 all: add jdk8 and 14 builds Apr 5, 2020
traceviewer all: don't expose errorprone / jsr deps through POM Mar 30, 2020
tracewriter all: don't expose errorprone / jsr deps through POM Mar 30, 2020
util all: don't expose errorprone / jsr deps through POM Mar 30, 2020
.gitignore move to perfmark from grpc May 9, 2019
.travis.yml all: add jdk8 and 14 builds Apr 5, 2020
CONTRIBUTING.md add a CONTRIBUTING doc Aug 13, 2019
LICENSE Initial commit Apr 25, 2019
NOTICE traceviewer: update to latest Catapult (#35) Mar 18, 2020
README.md all: bump README versions Mar 18, 2020
WORKSPACE all: bump deps in Bazel Mar 30, 2020
build.gradle all: add jdk8 and 14 builds Apr 5, 2020
gradlew all: update to gradle 6.3 Apr 5, 2020
gradlew.bat all: update to gradle 6.3 Apr 5, 2020
settings.gradle Add a copy of the catapult trace event viewer. Also start a new proje… Jul 6, 2019

README.md

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

  • Very Low Overhead: When enabled, tracing a function call adds about 70ns. Tracing is done in a lock-free, wait-free, thread local buffer, which avoids interfering with your latency-sensitive code.

  • Dynamically Enabled: PerfMark can be enabled or disabled at runtime. When disabled, PerfMark has zero overhead, taking advantage of the JIT compiler to remove the tracing.

  • Inter-thread Communication: Existing profilers have difficulty expressing which thread wakes up and executes work on another thread. PerfMark allows users to express this relationship explicitly, making for a clear picture of how code flows.

  • Small Library Size: The PerfMark tracing API is only 5 KB in size, and has minimal dependencies making it easy to include in other projects. If no backend for recording the trace is present, the library safely disables itself.

  • Multiple Java Versions: The PerfMark API supports Java 6, making it easy to include on older or constrained environments. Additionally, PerfMark includes optimized backends for Java 6, Java 7, and Java 9. Each of these backends is automatically loaded at runtime (if possible) and uses advanced JVM features for maximum speed.

  • Chrome Trace Viewer Integration: PerfMark can export to the Chrome Trace Event Format, making it easy to view in your Web Browser.

Usage

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

  • io.perfmark:perfmark-api:0.21.0
  • io.perfmark:perfmark-traceviewer:0.21.0

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.

You can’t perform that action at this time.