xref: /aosp_15_r20/external/perfmark/README.md (revision 27e8546d0ef5f99cf83d5252272c7dd38d18d29a) 
1# PerfMark
2
3![PerfMark Hummingbird](doc/perfmark.png "PerfMark")
4
5PerfMark is a low-overhead, manually-instrumented, tracing library for Java.  Users can add the
6tracing function calls to their code to see how long each part takes.
7
8## Features
9
10*   **Very Low Overhead**:  When enabled, tracing a function call adds about **70ns**.   Tracing is
11    done in a lock-free, wait-free, thread local buffer, which avoids interfering with your
12    latency-sensitive code.
13
14*   **Dynamically Enabled**: PerfMark can be enabled or disabled at runtime.  When disabled,
15    PerfMark has *zero overhead*, taking advantage of the JIT compiler to remove the tracing.
16
17*   **Inter-thread Communication**: Existing profilers have difficulty expressing which thread
18    wakes up and executes work on another thread.  PerfMark allows users to express this
19    relationship explicitly, making for a clear picture of how code flows.
20
21*   **Small Library Size**: The PerfMark tracing API is only *5 KB* in size, and has minimal
22    dependencies making it easy to include in other projects.  If no backend for recording the trace
23    is present, the library safely disables itself.
24
25*   **Multiple Java Versions**: The PerfMark API supports Java 6, making it easy to include on
26    older or constrained environments.  Additionally, PerfMark includes optimized backends for
27    Java 6, Java 7, and Java 9.  Each of these backends is automatically loaded at runtime
28    (if possible) and uses advanced JVM features for maximum speed.
29
30*   **Chrome Trace Viewer Integration**: PerfMark can export to the Chrome Trace Event Format,
31    making it easy to view in your Web Browser.
32
33## Usage
34
35To use PerfMark, add the following dependencies to your `build.gradle`:
36```
37dependencies {
38    implementation 'io.perfmark:perfmark-api:0.25.0'
39    // Only needed for applications, not libraries.
40    implementation 'io.perfmark:perfmark-traceviewer:0.25.0'
41}
42```
43
44Or in your `pom.xml`:
45
46```
47    <dependency>
48      <groupId>io.perfmark</groupId>
49      <artifactId>perfmark-api</artifactId>
50      <version>0.25.0</version>
51    </dependency>
52```
53
54In your code, add the PerfMark tracing calls like so:
55
56```java
57Map<String, Header> parseHeaders(List<String> rawHeaders) {
58  try (TaskCloseable task = PerfMark.traceTask("Parse HTTP headers")) {
59    Map<String, String> headers = new HashMap<>();
60    for (String rawHeader : rawHeaders) {
61      Header header = parseHeader(rawHeader);
62      headers.put(header.name(), header);
63    }
64    return headers;
65  }
66}
67
68```
69
70PerfMark can also be used to record asynchronous work:
71
72```java
73Future<Response> buildResponse() {
74  try (TaskCloseable task = PerfMark.traceTask("Build Response")) {
75    Link link = PerfMark.linkOut();
76    return executor.submit(() -> {
77      try (TaskCloseable task2 = PerfMark.traceTask("Async Response")) {
78        PerfMark.linkIn(link);
79        return new Response(/* ... */);
80      }
81    });
82  }
83}
84```
85
86To view the traces in your browser, generate the HTML:
87
88```java
89  PerfMark.setEnabled(true);
90  PerfMark.event("My Task");
91  TraceEventViewer.writeTraceHtml();
92```
93
94The output looks like:
95
96![PerfMark Hummingbird](doc/screenshot.png "PerfMark")
97
98## Configuration
99PerfMark provides some System Properties that allow controlling how it initializes.  These can be set
100by providing them as JVM arguments.  (e.g. `-Dio.perfmark.PerfMark.startEnabled=true`)
101
102* `io.perfmark.PerfMark.startEnabled` controls if PerfMark starts enabled.  This boolean property
103    makes it possible to start tracing calls immediately.  This is helpful when it's difficult
104    to invoke `setEnabled()` on PerfMark before task tracing calls have started.
105
106* `io.perfmark.PerfMark.debug` controls if PerfMark can log initializing steps.  This property
107    exists to disable class loading of the logger package (currently `java.util.logging`).  If
108    the debug property is set, the logger settings still need to be configured to report the logs.
109    By default, all PerfMark logs use level `FINE` (SLF4J `DEBUG`) or lower, which means that they
110    usually need additional setup to print.
111
112    In addition to initialization, the debug property controls if other tracing failures can be
113    logged. When calls involving deferred execution are used (e.g.
114    `startTask(T, StringFunction<T>)`), the String function provided may throw an exception.  In
115    these cases, the exception is silently ignored.  This makes it easy to ensure the start/stop
116    call parity is maintained.  To view these failures, the debug property can be set to log such
117    problems.  As above, the PerfMark logger should be configured as well to report these.
118
119## Versioning and API Stability
120
121PerfMark uses Semantic Versioning, and thus will not break existing APIs within a minor version
122update.  PerfMark may need to disable some functionality, and thus may need to make some tracing
123calls become No-ops.  In such cases, it will remain safe to call these functions being recorded.
124
125## Users
126
127PerfMark was designed originally for [gRPC](https://github.com/grpc/grpc-java). It is also used
128by [Zuul](https://github.com/Netflix/zuul).
129