Capture reflection logs

Capture reflection logs from the instrumented debug build by running the instrumented tests in src/androidTest or by running UI journeys, as described in references/journeys.md. The examples use the application ID com.example.app and a device with API level 29 or higher.

Build and instrument the debug APK

./gradlew :app:assembleDebug
mkdir -p app/build/r8-assistant
java -jar "$R8_ASSISTANT_JAR" instrument \
  --input app/build/outputs/apk/debug/app-debug.apk \
  --output app/build/r8-assistant/app-debug-instrumented.apk

With product flavors, the APK path contains the flavor, for example app/build/outputs/apk/free/debug/app-free-debug.apk.

instrument refuses an APK that is neither debuggable nor signed only with the debug key. It aligns the instrumented APK and signs it with the debug keystore.

Install the instrumented APK

adb install -r app/build/r8-assistant/app-debug-instrumented.apk

Always install with adb install -r. ./gradlew installDebug, connectedAndroidTest and android run install the APK without instrumentation, and connectedAndroidTest also uninstalls the app, which deletes its data. If the install fails, see references/troubleshooting.md.

Log path

The app writes the log to a path that depends on the API level of the device:

  • API level 29 and higher: /sdcard/Android/media/com.example.app/additional_test_output/reflection_log.json
  • API levels 16 to 28: /sdcard/Android/data/com.example.app/files/test_data/reflection_log.json
  • On API level 15 and lower, the app writes no log.

The path uses the application ID of the installed APK, including any applicationIdSuffix of the debug build.

Record a test run or journey

Stop the app and delete any old log on the device:

log=/sdcard/Android/media/com.example.app/additional_test_output/reflection_log.json
adb shell am force-stop com.example.app
adb shell rm -f "$log"

Run the instrumented tests with am instrument or run a UI journey, as described in references/journeys.md. For a UI journey, find the launcher activity of the installed app (from AndroidManifest.xml on API levels 16 to 23) and start it:

adb shell cmd package resolve-activity --brief com.example.app
adb shell am start -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -n com.example.app/com.example.app.MainActivity

Then pull the log into the state directory and delete the copy on the device:

log=/sdcard/Android/media/com.example.app/additional_test_output/reflection_log.json
adb pull "$log" app/build/r8-assistant/debug-settings.json
adb shell rm -f "$log"

Repeat for each separate test run or journey, with one file per run, such as debug-sync.json.

If the instrumented debug build crashes in the same way as the release build, R8 is not the cause. Report the crash and stop.

Log format

The log has one JSON object per line.

Before each distinct reflective call, the app writes a request line with the event type, an ID, the top five frames of the call stack, and the arguments. After the call returns, it writes the result for that ID:

{"event": "CLASS_FOR_NAME", "id": 3, "stack": ["com.example.app.settings.ThemeLoader.load(ThemeLoader.java:42)", "com.example.app.settings.SettingsFragment.onViewCreated(SettingsFragment.kt:31)"], "args": ["com.example.app.settings.DarkTheme", "true", "null"]}
{"returned": 3, "result": "com.example.app.settings.DarkTheme"}

The event types group into eight categories:

  • Class lookup and instantiation: CLASS_FOR_NAME, CLASS_NEW_INSTANCE, CLASS_LOADER_LOAD_CLASS, UNSAFE_ALLOCATE_INSTANCE.
  • Methods, fields and constructors: CLASS_GET_METHOD, CLASS_GET_DECLARED_METHOD, CLASS_GET_METHODS, CLASS_GET_DECLARED_METHODS, CLASS_GET_FIELD, CLASS_GET_DECLARED_FIELD, CLASS_GET_FIELDS, CLASS_GET_DECLARED_FIELDS, CLASS_GET_CONSTRUCTOR, CLASS_GET_DECLARED_CONSTRUCTOR, CLASS_GET_CONSTRUCTORS, CLASS_GET_DECLARED_CONSTRUCTORS.
  • Annotations on classes and members: CLASS_GET_ANNOTATION, CLASS_GET_ANNOTATIONS, CLASS_IS_ANNOTATION_PRESENT, FIELD_GET_ANNOTATION, FIELD_GET_ANNOTATIONS, FIELD_IS_ANNOTATION_PRESENT, METHOD_GET_ANNOTATION, METHOD_GET_ANNOTATIONS, METHOD_IS_ANNOTATION_PRESENT, CONSTRUCTOR_GET_ANNOTATION, CONSTRUCTOR_GET_ANNOTATIONS, CONSTRUCTOR_IS_ANNOTATION_PRESENT (covering both getAnnotation(s) and getDeclaredAnnotation(s)).
  • Generic supertypes and member signatures: CLASS_GET_GENERIC_SUPERCLASS, CLASS_GET_GENERIC_INTERFACES, METHOD_GET_GENERIC_PARAMETER_TYPES, METHOD_GET_GENERIC_RETURN_TYPE, METHOD_GET_GENERIC_EXCEPTION_TYPES, FIELD_GET_GENERIC_TYPE.
  • Nested and enclosing classes: CLASS_GET_DECLARED_CLASSES, CLASS_GET_CLASSES, CLASS_GET_ENCLOSING_CLASS, CLASS_GET_DECLARING_CLASS.
  • Enums: ENUM_VALUE_OF, CLASS_GET_ENUM_CONSTANTS.
  • Class metadata and type checks: CLASS_GET_NAME, CLASS_GET_PACKAGE, CLASS_GET_SUPERCLASS, CLASS_GET_COMPONENT_TYPE, CLASS_IS_ASSIGNABLE_FROM, CLASS_IS_INSTANCE, CLASS_CAST, CLASS_AS_SUBCLASS, CLASS_FLAG.
  • Concurrency, proxies, services and bundles: ATOMIC_FIELD_UPDATER_NEW_UPDATER, PROXY_NEW_PROXY_INSTANCE, SERVICE_LOADER_LOAD and RESOURCE_BUNDLE_GET_BUNDLE.

Results are class names, member signatures or booleans, and an object shows as the name of its class. Four kinds of results need a note:

  • RESOURCE_BUNDLE_GET_BUNDLE returns the class of the bundle, such as com.example.app.i18n.Messages_en, or java.util.PropertyResourceBundle when the bundle is a properties file.
  • CLASS_GET_GENERIC_SUPERCLASS, CLASS_GET_GENERIC_INTERFACES, METHOD_GET_GENERIC_PARAMETER_TYPES, METHOD_GET_GENERIC_RETURN_TYPE, METHOD_GET_GENERIC_EXCEPTION_TYPES and FIELD_GET_GENERIC_TYPE return the name of each plain class, and <raw type><...> without type arguments (such as com.google.gson.reflect.TypeToken<...>) for each parameterized type, or the runtime class name (libcore.reflect.ParameterizedTypeImpl on ART) when getRawType throws.
  • Annotation queries return the annotation type names (plus class:<type> and interface:<type> entries for Class-valued annotation elements), or a boolean for *_IS_ANNOTATION_PRESENT.
  • ENUM_VALUE_OF and CLASS_GET_ENUM_CONSTANTS return the enum constant name(s), and SERVICE_LOADER_LOAD returns the loaded provider class names.

Limits of the log

  • Distinct events only: the app writes each distinct combination of event, stack and arguments once per process, and each distinct result once per event. The log shows which reflection happened, not how often.
  • Failures: a request line without a result line means that the call threw, or that the process died before the call returned. The log records no exception type; take it from logcat.
  • Ignored code: the log leaves out reflection on java., javax. and android. classes. It also leaves out internal reflection within the same library group (such as an androidx.foo.* class reflecting on androidx.foo.*, or kotlin. and kotlinx. code reflecting on kotlin. and kotlinx.).
  • Library reflection: reflection that AndroidX and Kotlin code does on app classes, third-party classes, or another library group (such as Room instantiating WorkDatabase_Impl) is in the log. The five logged frames are often all library frames.
  • Platform code: only code in the APK is instrumented. Reflection inside the Android platform, such as the creation of activities from the manifest, of custom views by LayoutInflater, and of security provider services by java.security.Provider, has no events.
  • JNI calls: native code that looks up classes, methods or fields through JNI (FindClass, GetMethodID, GetFieldID) does not go through Java bytecode and has no events.
  • Class loaders: loadClass calls through a variable of a subclass type, such as DexClassLoader, and super.loadClass calls have no events.
  • Module bundles: the ResourceBundle.getBundle overloads that take a java.lang.Module have no events.
  • ServiceLoader: SERVICE_LOADER_LOAD iterates the loader to record the loaded provider classes; a provider whose instantiation throws during loading has no entry in the result.
  • One process at a time: each new app process truncates the log, so app restarts, a second app process, and per-test processes of a test runner overwrite earlier events. Pull the log before the app restarts.
  • Crashes: when the app crashes or is killed, the log ends there. Treat the journey as failed and run it again after the cause is fixed.
  • Empty logs: an empty log means that the journey made no reflective call that the log records, or that the installed APK is not the instrumented one. See references/troubleshooting.md.

Privacy

The log contains class names, member names, stack frames and the string arguments of reflective calls, but no field values.

Keep the logs in the state directory, delete each log on the device after the pull, and send the logs nowhere.