blob: 0b3c78bf7e996283d6336ad1b0f6bfe87295782e [file] [view]
# 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](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
```shell
./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
```shell
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](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:
```shell
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](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:
```shell
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:
```shell
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:
```json
{"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](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.