Full ETDump support in Java

[psiddh]

Document how to build with profiling support
API to write ETDump to a user-specified location
API to enable profiling capture at module load time (similar to C++ APIs, separate from build-time gating)

[psiddh]

#16359

[psiddh]

🎯 ETDump Android API - Usage Examples

📚 Complete API Reference

// Global Control (ETDump class)
ETDump.enableProfiling() // Enable for subsequently loaded modules
ETDump.disableProfiling() // Disable profiling
ETDump.isProfilingEnabled() // Check current state

// Per-Module Operations (Module class)
module.writeETDumpToPath(String path) // Write to custom path
module.getETDumpData() // Get data as byte[]
module.etdump() // Legacy (writes to /data/local/tmp)

---

1️⃣ Basic Profiling

public void basicProfiling() {
// Enable profiling
ETDump.enableProfiling();

  // Load and run model
  Module module = Module.load(modelPath);
  Tensor input = Tensor.fromBlob(inputData, shape);
  EValue[] outputs = module.forward(EValue.from(input));

  // Write to app cache directory (no root needed!)
  String profilePath = getCacheDir() + "/basic_profile.etdump";
  module.writeETDumpToPath(profilePath);

  Log.i(TAG, "Profile saved to: " + profilePath);

  // Disable profiling
  ETDump.disableProfiling();

}

// Analyze:
// adb pull /data/data/com.example.app/cache/basic_profile.etdump .
// python -m executorch.sdk.inspector.inspector_cli
// --etdump_path basic_profile.etdump --model_path model.pte

---

2️⃣ Debug Slow Inferences

public void detectAndProfileSlowInferences() {
Module module = Module.load(modelPath);

  for (int i = 0; i < 100; i++) {
      long start = System.currentTimeMillis();
      module.forward(inputs);
      long duration = System.currentTimeMillis() - start;

      // Automatically profile if inference is slow
      if (duration > 500) {  // Slower than 500ms
          Log.w(TAG, "Slow inference detected: " + duration + "ms");

          // Enable profiling and re-run
          ETDump.enableProfiling();
          Module debugModule = Module.load(modelPath);
          debugModule.forward(inputs);

          String debugPath = getExternalFilesDir(null) +
                            "/slow_run_" + duration + "ms_" +
                            System.currentTimeMillis() + ".etdump";
          debugModule.writeETDumpToPath(debugPath);

          Log.i(TAG, "Debug profile saved: " + debugPath);
          ETDump.disableProfiling();

          break; // Profile once
      }
  }

}

---

3️⃣ A/B Test Model Performance

public void compareModelVersions() {
// Profile Model V1
ETDump.enableProfiling();
Module modelV1 = Module.load("model_v1.pte");

  long startV1 = System.nanoTime();
  modelV1.forward(inputs);
  long durationV1 = System.nanoTime() - startV1;

  modelV1.writeETDumpToPath(getCacheDir() + "/model_v1_profile.etdump");

  // Profile Model V2
  Module modelV2 = Module.load("model_v2.pte");

  long startV2 = System.nanoTime();
  modelV2.forward(inputs);
  long durationV2 = System.nanoTime() - startV2;

  modelV2.writeETDumpToPath(getCacheDir() + "/model_v2_profile.etdump");

  ETDump.disableProfiling();

  // Compare
  Log.i(TAG, "Model V1: " + (durationV1 / 1_000_000) + "ms");
  Log.i(TAG, "Model V2: " + (durationV2 / 1_000_000) + "ms");

  String winner = durationV1 < durationV2 ? "V1" : "V2";
  Log.i(TAG, "Winner: Model " + winner);

}

---

4️⃣ Remote-Controlled Profiling

public class ModelRunner {
private FirebaseRemoteConfig remoteConfig;

  public void runInferenceWithRemoteControl() {
      // Check remote config (can enable for specific users/devices)
      boolean shouldProfile = remoteConfig.getBoolean("enable_profiling");
      String userId = getCurrentUserId();

      if (shouldProfile) {
          Log.i(TAG, "Remote profiling enabled for user: " + userId);
          ETDump.enableProfiling();
      }

      Module module = Module.load(modelPath);
      module.forward(inputs);

      if (ETDump.isProfilingEnabled()) {
          // Upload to analytics server
          byte[] profileData = module.getETDumpData();
          if (profileData != null) {
              uploadProfileToServer(userId, profileData);
              Log.i(TAG, "Profile uploaded: " + profileData.length + " bytes");
          }

          ETDump.disableProfiling();
      }
  }

  private void uploadProfileToServer(String userId, byte[] data) {
      // Upload to your analytics backend
      analyticsClient.uploadProfile(userId, data);
  }

}

---

5️⃣ Conditional Profiling (Debug Builds Only)

public void conditionalProfiling() {
// Only profile in debug builds
if (BuildConfig.DEBUG) {
ETDump.enableProfiling();
}

  Module module = Module.load(modelPath);
  module.forward(inputs);

  if (BuildConfig.DEBUG) {
      String timestamp = new SimpleDateFormat("yyyyMMdd_HHmmss")
          .format(new Date());
      String path = getExternalFilesDir(null) +
                   "/debug_profile_" + timestamp + ".etdump";
      module.writeETDumpToPath(path);

      // Share file for analysis
      shareFile(path);

      ETDump.disableProfiling();
  }

}

private void shareFile(String path) {
Intent shareIntent = new Intent(Intent.ACTION_SEND);
shareIntent.setType("application/octet-stream");
shareIntent.putExtra(Intent.EXTRA_STREAM, Uri.fromFile(new File(path)));
startActivity(Intent.createChooser(shareIntent, "Share profile"));
}

---

6️⃣ Device-Specific Profiling

public void profileOnSpecificDevices() {
// Only profile on high-end devices
boolean isHighEnd = Runtime.getRuntime().availableProcessors() >= 8 &&
getMemoryInfo().totalMem > 6L * 1024 * 1024 * 1024; // 6GB+

  // Or profile on specific device models
  boolean isTargetDevice = Build.MODEL.equals("Pixel 8") ||
                          Build.MODEL.contains("Galaxy S24");

  if (isHighEnd || isTargetDevice) {
      ETDump.enableProfiling();
      Log.i(TAG, "Profiling enabled on device: " + Build.MODEL);
  }

  Module module = Module.load(modelPath);
  module.forward(inputs);

  if (ETDump.isProfilingEnabled()) {
      String deviceProfile = getExternalFilesDir(null) +
                            "/profile_" + Build.MODEL.replace(" ", "_") + ".etdump";
      module.writeETDumpToPath(deviceProfile);
      ETDump.disableProfiling();
  }

}

---

7️⃣ CI/CD Performance Regression Test

@test
public void testModelPerformanceRegression() {
// Enable profiling for test
ETDump.enableProfiling();

  Module module = Module.load(testModelPath);

  // Warmup
  for (int i = 0; i < 3; i++) {
      module.forward(testInputs);
  }

  // Measure
  long[] times = new long[10];
  for (int i = 0; i < 10; i++) {
      long start = System.nanoTime();
      module.forward(testInputs);
      times[i] = System.nanoTime() - start;
  }

  // Calculate average
  long avgTime = Arrays.stream(times).sum() / times.length;
  long avgMs = avgTime / 1_000_000;

  // Save profile for CI analysis
  String ciProfilePath = new File(context.getCacheDir(), "ci_profile.etdump")
      .getAbsolutePath();
  assertTrue("Failed to write profile", module.writeETDumpToPath(ciProfilePath));

  // Assert performance
  assertTrue("Model regression: " + avgMs + "ms > 50ms threshold",
             avgMs < 50);

  Log.i(TAG, "✓ Performance test passed: " + avgMs + "ms");

  ETDump.disableProfiling();

}

---

8️⃣ Compare Backend Performance (XNNPACK vs CPU)

public void compareBackends() {
ETDump.enableProfiling();

  // Profile XNNPACK backend
  Module xnnpackModel = Module.load("model_xnnpack.pte");
  long xnnpackTime = benchmarkModel(xnnpackModel, 100);
  xnnpackModel.writeETDumpToPath(getCacheDir() + "/xnnpack_profile.etdump");

  // Profile CPU backend
  Module cpuModel = Module.load("model_cpu.pte");
  long cpuTime = benchmarkModel(cpuModel, 100);
  cpuModel.writeETDumpToPath(getCacheDir() + "/cpu_profile.etdump");

  // Profile Vulkan backend (if available)
  Module vulkanModel = Module.load("model_vulkan.pte");
  long vulkanTime = benchmarkModel(vulkanModel, 100);
  vulkanModel.writeETDumpToPath(getCacheDir() + "/vulkan_profile.etdump");

  ETDump.disableProfiling();

  // Results
  Log.i(TAG, "XNNPACK: " + xnnpackTime + "ms avg");
  Log.i(TAG, "CPU: " + cpuTime + "ms avg");
  Log.i(TAG, "Vulkan: " + vulkanTime + "ms avg");

  // Select best backend for production
  String bestBackend = selectFastestBackend(xnnpackTime, cpuTime, vulkanTime);
  saveBestBackendPref(bestBackend);

}

private long benchmarkModel(Module module, int iterations) {
long total = 0;
for (int i = 0; i < iterations; i++) {
long start = System.nanoTime();
module.forward(inputs);
total += System.nanoTime() - start;
}
return total / iterations / 1_000_000; // Return avg in ms
}

---

9️⃣ Programmatic Upload (No File I/O)

public void uploadProfileDirectly() {
ETDump.enableProfiling();

  Module module = Module.load(modelPath);
  module.forward(inputs);

  // Get data directly without writing to file
  byte[] profileData = module.getETDumpData();

  if (profileData != null) {
      // Compress before upload
      byte[] compressed = gzipCompress(profileData);

      // Upload to your analytics server
      AnalyticsClient.uploadProfileData(
          getUserId(),
          getDeviceInfo(),
          Build.MODEL,
          compressed
      );

      Log.i(TAG, "Profile uploaded: " + profileData.length +
                 " bytes (" + compressed.length + " compressed)");
  }

  ETDump.disableProfiling();

}

private byte[] gzipCompress(byte[] data) {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
try (GZIPOutputStream gzip = new GZIPOutputStream(baos)) {
gzip.write(data);
} catch (IOException e) {
Log.e(TAG, "Compression failed", e);
return data;
}
return baos.toByteArray();
}

---

🔟 Profile Multiple Models Sequentially

public void profileModelPipeline() {
ETDump.enableProfiling();

  // Profile detection model
  Module detector = Module.load("detector.pte");
  detector.forward(imageInput);
  detector.writeETDumpToPath(getCacheDir() + "/1_detector.etdump");

  // Profile classification model
  Module classifier = Module.load("classifier.pte");
  classifier.forward(detectionOutput);
  classifier.writeETDumpToPath(getCacheDir() + "/2_classifier.etdump");

  // Profile segmentation model
  Module segmenter = Module.load("segmenter.pte");
  segmenter.forward(classificationOutput);
  segmenter.writeETDumpToPath(getCacheDir() + "/3_segmenter.etdump");

  ETDump.disableProfiling();

  Log.i(TAG, "Full pipeline profiled - 3 stages");

}

---

1️⃣1️⃣ Selective Profiling (Profile 1 of N Runs)

public void profileSingleRunOfMany() {
Module module = Module.load(modelPath);

  for (int i = 0; i < 1000; i++) {
      // Only profile run #500
      if (i == 500) {
          ETDump.enableProfiling();
          Module profileModule = Module.load(modelPath);
          profileModule.forward(inputs);
          profileModule.writeETDumpToPath(
              getCacheDir() + "/run_500_of_1000.etdump"
          );
          ETDump.disableProfiling();
      } else {
          // Fast - no profiling overhead
          module.forward(inputs);
      }
  }

  Log.i(TAG, "1000 runs complete, 1 profiled");

}

---

1️⃣2️⃣ User-Triggered Profiling

public class InferenceActivity extends Activity {
private Module module;
private boolean profilingEnabled = false;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);

      module = Module.load(modelPath);

      // Debug menu option
      findViewById(R.id.enable_profiling_button).setOnClickListener(v -> {
          profilingEnabled = !profilingEnabled;
          if (profilingEnabled) {
              ETDump.enableProfiling();
              Toast.makeText(this, "Profiling enabled", Toast.LENGTH_SHORT).show();
          } else {
              ETDump.disableProfiling();
              Toast.makeText(this, "Profiling disabled", Toast.LENGTH_SHORT).show();
          }
      });

      findViewById(R.id.save_profile_button).setOnClickListener(v -> {
          String path = getExternalFilesDir(null) + "/user_profile_" +
                       System.currentTimeMillis() + ".etdump";
          if (module.writeETDumpToPath(path)) {
              Toast.makeText(this, "Profile saved: " + path,
                            Toast.LENGTH_LONG).show();
          }
      });
  }

  public void runInference() {
      module.forward(inputs);
      updateUI();
  }

}