Android ExecuTorch :Improve debuggability and Triage

[psiddh]

🚀 The feature, motivation and pitch

Design Overview: ETLogDumpService for Android Hosting Process

This design illustrates how native C++ logs are collected and exposed via an Android Java service (ETLogDumpService) inside the hosting process (e.g., an Android app or system service).

Architecture Diagram

Hosting Process (Android app)
┌───────────────────────────────────────────────────────────────────────────────┐
│ executorch.aar (library module) │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ ETLogDumpService (Java) │ │
│ │ • onLogCallback(String msg) ← JNI bridge from native C++ │ │
│ │ • ConcurrentLinkedQueue logsQueue │ │
│ │ • dump(FileDescriptor, PrintWriter, String[] args) │ │
│ │ └─> Iterates logsQueue and prints messages when dumpsys triggers │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Native Layer (C++) │
│ • Generates logs │
│ • Calls ETLogDumpService.onLogCallback() via JNI │
│ │
│ Trigger Flow │
│ adb shell dumpsys activity service / │
│ └──> Android framework calls ETLogDumpService.dump() │
└───────────────────────────────────────────────────────────────────────────────┘

• Outer box: Hosting process (Android app or system service)
• Inner box: executorch.aar library module providing ETLogDumpService
• JNI arrow: Native C++ code pushes logs into Java queue via JNI callback
• Trigger flow: adb shell dumpsys ... command triggers the dump() method

Design Details

1. JNI Callback to Java Service

• Native C++ code locates the ETLogDumpService Java class.

• It calls the Java method onLogCallback(String msg) via JNI using:

FindClass
GetMethodID
CallVoidMethod
This pattern allows native code to push each log message string into Java.

2. ConcurrentLinkedQueue for Log Buffering

• onLogCallback() pushes each incoming log message into a ConcurrentLinkedQueue.
• This queue is: Thread-safe & Non-blocking
• Suitable for multiple producer threads concurrently adding logs
• The queue buffers all logs until the dump() method is called.

3. Dumpsys Triggering Log Dump

• Running adb shell dumpsys activity service / invokes the Android framework to call:
• ETLogDumpService.dump(FileDescriptor, PrintWriter, String[] args)
• The overridden dump() method:
• Iterates through the ConcurrentLinkedQueue (e.g., polling until empty)
• Writes each log message to the PrintWriter output
• This mechanism uses dumpsys as a trigger to output collected logs on demand.

Design Considerations

• Queue Growth: Be mindful of unbounded queue growth if logs arrive faster than they are dumped.
• Consider using a bounded queue like ConcurrentRingBuffer to mitigate memory issues.
• Service Lifecycle: The host process must explicitly start ETLogDumpService early to begin collecting logs.

Alternatives

No response

Additional context

No response

RFC (Optional)

No response

[psiddh]

cc @GregoryComer @kirklandsign @jackzhxng @mergennachin

[kirklandsign]

Is the service shared between different apps?

[psiddh]

Is the service shared between different apps?

The service will be one per app (as apps link to each executorch library instance , and service is a resident of this library)
Also note that such kind of Android Services are not persistent , in other words, it runs when it gets invoked and immediately shuts-down once the dump / logging is completed.

[GregoryComer]

Thanks for writing this up. I'm in favor of implementing it, as described here. It should be quite useful.

On small thought - it would be nice to also expose a general log subscription API in Java, since with this proposal, we'll have the ability to do this easily. That could also allow users to access runtime logs from Java for their own purposes beyond exception handling.