Java / Android SDK

Perfetto has a Java tracing API for Android, in the dev.perfetto.sdk package. Like the Rust SDK, it is a language binding over the C SDK: the Java classes call into libperfetto_c through JNI, so Java trace events use the same core and produce the same trace format as every other Perfetto SDK.

NOTE: The Java SDK is currently Android-internal. PerfettoTrace is a hidden (@hide) platform API, it depends on Android runtime features, and it is gated behind the enable_perfetto_android_java_sdk build flag. It is not yet a general-purpose, cross-platform Java library, and it inherits the C SDK's stability caveat.

When to use it

For most Android app instrumentation, prefer the standard android.os.Trace API. It is fully supported by Perfetto (see ATrace instrumentation) and is the simplest path for slices on the timeline.

Reach for the Perfetto Java SDK when you need richer track events than android.os.Trace offers — typed debug annotations, counters, flows, custom and nested tracks, correlation ids, or interned fields — from Java or Kotlin on Android.

Shape of the API

The entry point is dev.perfetto.sdk.PerfettoTrace. Events are built with a fluent builder and committed with emit():

import dev.perfetto.sdk.PerfettoTrace;

// Register once (in-process or system backend).
PerfettoTrace.register(/* isBackendInProcess= */ false);

PerfettoTrace.Category category = new PerfettoTrace.Category("rendering");

PerfettoTrace.begin(category, "DrawGame")
    .addArg("player_number", 1)
    .emit();
// ...
PerfettoTrace.end(category).emit();

The builder mirrors the C SDK's track-event capabilities: instant, begin / end, counter, and state; addArg(...) for debug annotations; usingTrack / usingNamedTrack / usingCounterTrack for custom tracks; setFlow / addFlow; and setCorrelationId.

Source

  • Java API: src/android_sdk/java/main/dev/perfetto/sdk/
  • JNI glue: src/android_sdk/jni/
  • Native layer over the C SDK: src/android_sdk/perfetto_sdk_for_jni/tracing_sdk.h

Next steps