Creare e misurare manualmente i profili di riferimento

Ti consigliamo vivamente di automatizzare la generazione delle regole del profilo utilizzando la libreria Macrobenchmark di Jetpack per ridurre il lavoro manuale e aumentare la scalabilità generale. Tuttavia, è possibile creare e misurare manualmente le regole del profilo nella tua app.

Definire manualmente le regole del profilo

Puoi definire manualmente le regole del profilo in un'app o in un modulo della raccolta creando un file denominato baseline-prof.txt nella directory src/main. Si tratta della stessa cartella che contiene il file AndroidManifest.xml.

Il file specifica una regola per riga. Ogni regola rappresenta un pattern per la corrispondenza di metodi o classi nell'app o nella libreria che devono essere ottimizzati.

La sintassi di queste regole è un superset del formato del profilo ART (HRF) leggibile da persone quando si utilizza adb shell profman --dump-classes-and-methods. La sintassi è simile alla sintassi per descrittori e firme, ma consente di utilizzare i caratteri jolly per semplificare la procedura di scrittura delle regole.

L'esempio seguente mostra alcune regole del profilo di riferimento incluse nella raccolta Compose di Jetpack:

HSPLandroidx/compose/runtime/ComposerImpl;->updateValue(Ljava/lang/Object;)V
HSPLandroidx/compose/runtime/ComposerImpl;->updatedNodeCount(I)I
HLandroidx/compose/runtime/ComposerImpl;->validateNodeExpected()V
PLandroidx/compose/runtime/CompositionImpl;->applyChanges()V
HLandroidx/compose/runtime/ComposerKt;->findLocation(Ljava/util/List;I)I
Landroidx/compose/runtime/ComposerImpl;

Puoi provare a modificare le regole del profilo in questo progetto Compiler Explorer di esempio. Tieni presente che Compiler Explorer supporta solo il formato del profilo ART leggibile da persone (HRF), pertanto le stringhe jolly non sono supportate.

Sintassi delle regole

Queste regole possono assumere una di due forme per scegliere come target metodi o classi:

[FLAGS][CLASS_DESCRIPTOR]->[METHOD_SIGNATURE]

Una regola di classe utilizza il seguente pattern:

[CLASS_DESCRIPTOR]

Per una descrizione dettagliata, consulta la tabella seguente:

Questi pattern possono avere caratteri jolly per consentire a una singola regola di includere più metodi o classi. Per assistenza guidata durante la scrittura con la sintassi delle regole in Android Studio, consulta il plug-in Android Baseline Profiles.

Un esempio di regola con caratteri jolly potrebbe avere il seguente aspetto:

HSPLandroidx/compose/ui/layout/**->**(**)**

Tipi supportati nelle regole del profilo di baseline

Le regole del profilo di riferimento supportano i seguenti tipi. Per informazioni dettagliate su questi tipi, consulta il formato file eseguibile Dalvik (DEX).

Inoltre, le librerie possono definire regole che vengono pacchettizzate negli elementi AAR. Quando crei un APK per includere questi elementi, le regole vengono unite, in modo simile a come viene eseguita l'unione del manifest, e compilate in un profilo ART binario compatto specifico per l'APK.

ART sfrutta questo profilo quando l'APK viene utilizzato sui dispositivi per compilare AOT un insieme specifico di app al momento dell'installazione su Android 9 (livello API 28) o Android 7 (livello API 24) quando si utilizza ProfileInstaller.

Raccogliere manualmente i profili di riferimento

Puoi generare manualmente un profilo di riferimento senza configurare la libreria Macrobenchmark e creare automazioni dell'interfaccia utente dei tuoi percorsi utente critici. Sebbene consigliamo di utilizzare i macro benchmark, potrebbe non essere sempre possibile. Ad esempio, se utilizzi un sistema di compilazione diverso da Gradle, non puoi utilizzare il plug-in Gradle del profilo di riferimento. In questi casi, puoi raccogliere manualmente le regole del profilo di riferimento. Questa operazione è molto più semplice se utilizzi un dispositivo o un emulatore con API 34 o versioni successive. Sebbene sia ancora possibile con livelli API inferiori, richiede accesso come amministratore e devi utilizzare un emulatore che esegue un'immagine AOSP. Puoi raccogliere le regole direttamente seguendo questa procedura:

1. Installa una versione release della tua app su un dispositivo di test. Il tipo di compilazione dell'app deve essere ottimizzato per R8 e non essere di tipo di debug per un profilo accurato.
2. Assicurati che i profili non siano già stati compilati.

   API 34 e versioni successive

   adb shell cmd package compile -f -m verify $PACKAGE_NAME
   adb shell pm art clear-app-profiles $PACKAGE_NAME

   API 33 e versioni precedenti

   adb root
   adb shell cmd package compile --reset $PACKAGE_NAME

   Se il tuo APK ha una dipendenza dalla libreria Profile Installer di Jetpack, la libreria avvia un profilo al primo avvio dell'APK. Questo può interferire con la procedura di generazione del profilo, quindi disattivalo con il seguente comando:

   adb shell am broadcast -a androidx.profileinstaller.action.SKIP_FILE $PACKAGE_NAME/androidx.profileinstaller.ProfileInstallReceiver

3. Esegui l'app e naviga manualmente nei percorsi degli utenti critici per i quali vuoi raccogliere un profilo.
4. Chiedi ad ART di scaricare i profili. Se il tuo APK ha una dipendenza dalla libreria Profile Installer di Jetpack, utilizzala per eseguire il dump dei profili:

   adb shell am broadcast -a androidx.profileinstaller.action.SAVE_FILE $PACKAGE_NAME/androidx.profileinstaller.ProfileInstallReceiver
   adb shell am force-stop $PACKAGE_NAME

   Se non utilizzi Profile Installer, esegui il dump dei profili manualmente su un emulatore utilizzando il seguente comando:

   adb root
   adb shell killall -s SIGUSR1 $PACKAGE_NAME
   adb shell am force-stop $PACKAGE_NAME

5. Attendi almeno cinque secondi per consentire il completamento della generazione del profilo.
6. Converti i profili binari generati in testo:

   API 34 e versioni successive

   adb shell pm dump-profiles --dump-classes-and-methods $PACKAGE_NAME

   API 33 e versioni precedenti

   Determina se è stato creato un profilo di riferimento o un profilo corrente. Un profilo di riferimento si trova nella seguente posizione:

   /data/misc/profiles/ref/$$PACKAGE_NAME/primary.prof

   Un profilo corrente si trova nella seguente posizione:

   /data/misc/profiles/cur/0/$PACKAGE_NAME/primary.prof

   Determina la posizione dell'APK:

   adb root
   adb shell pm path $PACKAGE_NAME

   Esegui la conversione:

   adb root
   adb shell profman --dump-classes-and-methods --profile-file=$PROFILE_PATH --apk=$APK_PATH > /data/misc/profman/$PACKAGE_NAME-primary.prof.txt

7. Utilizza adb per recuperare il profilo sottoposto a dump dal dispositivo:

   adb pull /data/misc/profman/$PACKAGE_NAME-primary.prof.txt PATH_TO_APP_MODULE/src/main/

Le regole del profilo generate vengono estratte e installate nel modulo dell'app. La volta successiva che crei l'app, il profilo di riferimento viene incluso. Verificalo seguendo i passaggi descritti in Problemi di installazione.

Misurare manualmente i miglioramenti delle app

Ti consigliamo vivamente di misurare i miglioramenti dell'app tramite il benchmarking. Tuttavia, se vuoi misurare i miglioramenti manualmente, puoi iniziare misurando la avvio dell'app non ottimizzata come riferimento.

PACKAGE_NAME=com.example.app
# Force Stop App
adb shell am force-stop $PACKAGE_NAME
# Reset compiled state
adb shell cmd package compile --reset $PACKAGE_NAME
# Measure App startup
# This corresponds to `Time to initial display` metric.
adb shell am start-activity -W -n $PACKAGE_NAME/.ExampleActivity \
 | grep "TotalTime"

Poi, carica lateralmente il profilo di baseline.

# Unzip the Release APK first.
unzip release.apk
# Create a ZIP archive.
# The name should match the name of the APK.
# Copy `baseline.prof{m}` and rename it `primary.prof{m}`.
cp assets/dexopt/baseline.prof primary.prof
cp assets/dexopt/baseline.profm primary.profm
# Create an archive.
zip -r release.dm primary.prof primary.profm
# Confirm that release.dm only contains the two profile files:
unzip -l release.dm
# Archive:  release.dm
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#      3885  1980-12-31 17:01   primary.prof
#      1024  1980-12-31 17:01   primary.profm
# ---------                     -------
#                               2 files
# Install APK + Profile together.
adb install-multiple release.apk release.dm

Per verificare che il pacchetto sia stato ottimizzato durante l'installazione, esegui il seguente comando:

# Check dexopt state.
adb shell dumpsys package dexopt | grep -A 1 $PACKAGE_NAME

L'output deve indicare che il pacchetto è compilato:

[com.example.app]
  path: /data/app/~~YvNxUxuP2e5xA6EGtM5i9A==/com.example.app-zQ0tkJN8tDrEZXTlrDUSBg==/base.apk
  arm64: [status=speed-profile] [reason=install-dm]

Ora puoi misurare il rendimento all'avvio dell'app come prima, ma senza resettare lo stato compilato. Assicurati di non reimpostare lo stato compilato per il pacchetto.

# Force stop app
adb shell am force-stop $PACKAGE_NAME
# Measure app startup
adb shell am start-activity -W -n $PACKAGE_NAME/.ExampleActivity \
 | grep "TotalTime"

Profili di riferimento e profgen

Questa sezione descrive cosa fa lo strumento profgen durante la creazione di una versione di codice macchina compatta di un profilo di riferimento.

Profgen-cli è utile per la compilazione, l'introspezione e la transpilazione dei profili ART, in modo che possano essere installati sui dispositivi Android indipendentemente dalla versione dell'SDK di destinazione.

Profgen-cli è un'interfaccia a riga di comando che compila l'HRF di un profilo di riferimento nel suo formato compilato. L'interfaccia a riga di comando è disponibile anche nel repository cmdline-tools nell'ambito dell'SDK Android.

Queste funzionalità sono disponibili nel ramo studio-main:

➜ ../cmdline-tools/latest/bin
apkanalyzer
avdmanager
lint
profgen
retrace
screenshot2
sdkmanager

Crea profili binari compatti con Profgen-cli

I comandi disponibili con Profgen-cli sono bin, validate e dumpProfile. Per visualizzare i comandi disponibili, usa profgen --help:

➜  profgen --help
Usage: profgen options_list
Subcommands:
    bin - Generate Binary Profile
    validate - Validate Profile
    dumpProfile - Dump a binary profile to a HRF

Options:
    --help, -h -> Usage info

Utilizza il comando bin per generare il profilo binario compatto. Di seguito è riportato un esempio di chiamata:

profgen bin ./baseline-prof.txt \
  --apk ./release.apk \
  --map ./obfuscation-map.txt \
  --profile-format v0_1_0_p \
  --output ./baseline.prof \

Per visualizzare le opzioni disponibili, usa profgen bin options_list:

Usage: profgen bin options_list
Arguments:
    profile -> File path to Human Readable profile { String }
Options:
    --apk, -a -> File path to apk (always required) { String }
    --output, -o -> File path to generated binary profile (always required)
    --map, -m -> File path to name obfuscation map { String }
    --output-meta, -om -> File path to generated metadata output { String }
    --profile-format, -pf [V0_1_0_P] -> The ART profile format version
      { Value should be one of [
         v0_1_5_s, v0_1_0_p, v0_0_9_omr1, v0_0_5_o, v0_0_1_n
        ]
      }
    --help, -h -> Usage info

Il primo argomento rappresenta il percorso del file HRF baseline-prof.txt.

Profgen-cli richiede anche il percorso della build release dell'APK e una mappa di offuscamento utilizzata per offuscare l'APK quando si utilizza R8 o Proguard. In questo modo, profgen può tradurre i simboli di origine nel HRF nei nomi offuscati corrispondenti durante la creazione del profilo compilato.

Poiché i formati dei profili ART non sono compatibili con le versioni precedenti o successive, fornisci un formato del profilo in modo che profgen imposti i metadati del profilo (profm) che puoi utilizzare per transcodificare un formato del profilo ART in un altro, se necessario.

Formati dei profili e versioni della piattaforma

Quando scegli un formato del profilo, hai a disposizione le seguenti opzioni:

Copia i file di output baseline.prof e baseline.profm nella assets o nella cartella dexopt nell'APK.

Mappe di offuscamento

Devi fornire la mappa di offuscamento solo se l'HRF utilizza i simboli di origine. Se l'HRF viene generato da una release build già offuscata e non è necessaria alcuna mappatura, puoi ignorare questa opzione e copiare gli output nella cartella assets o dexopt.

Installazione tradizionale dei profili di riferimento

I profili di riferimento vengono in genere caricati su un dispositivo in due modi.

Utilizzare install-multiple con DexMetadata

Sui dispositivi con API 28 e versioni successive, il client di Google Play scarica il payload APK e DexMetadata (DM) per una versione dell'APK in fase di installazione. Il file DM contiene le informazioni sul profilo che vengono trasmesse a Package Manager sul dispositivo.

L'APK e il DM vengono installati nell'ambito di una singola sessione di installazione utilizzando qualcosa di simile a:

adb install-multiple base.apk base.dm

Jetpack ProfileInstaller

Sui dispositivi con livello API 29 e versioni successive, la libreria Jetpack ProfileInstaller fornisce un meccanismo alternativo per installare un profilo pacchettizzato in assetso dexopt dopo l'installazione dell'APK sul dispositivo. ProfileInstaller viene richiamato da ProfileInstallReceiver o direttamente dall'app.

La libreria ProfileInstaller transcodifica il profilo in base alla versione SDK del dispositivo di destinazione e lo copia nella directory cur sul dispositivo (una directory di staging specifica per il pacchetto per i profili ART sul dispositivo).

Quando il dispositivo è inattivo, il profilo viene rilevato da un processo chiamato bg-dexopt sul dispositivo.

Eseguire il sideload di un profilo di riferimento

Questa sezione descrive come installare un profilo di riferimento a partire da un APK.

Trasmettere con androidx.profileinstaller

Sui dispositivi con API 24 e versioni successive, puoi trasmettere un comando per installare il profilo:

# Broadcast the install profile command - moves binary profile from assets
#     to a location where ART uses it for the next compile.
#     When successful, the following command prints "1":
adb shell am broadcast \
    -a androidx.profileinstaller.action.INSTALL_PROFILE \
    <pkg>/androidx.profileinstaller.ProfileInstallReceiver

# Kill the process
am force-stop <pkg>

# Compile the package based on profile
adb shell cmd package compile -f -m speed-profile <pkg>

ProfileInstaller non è presente nella maggior parte degli APK con profili di riferimento, che si trovano in circa 77.000 delle 450.000 app su Play, anche se è presente in ogni APK che utilizza Compose. Questo perché le librerie possono fornire profili senza dichiarare una dipendenza da ProfileInstaller. L'aggiunta di una dipendenza in ogni biblioteca con un profilo si applica a partire da Jetpack.

Utilizzare install-multiple con profgen o DexMetaData

Sui dispositivi con API 28 e versioni successive, puoi eseguire il sideload di un profilo di riferimento senza dover avere la libreria ProfileInstaller nell'app.

A tal fine, utilizza Profgen-cli:

profgen extractProfile \
        --apk app-release.apk \
        --output-dex-metadata app-release.dm \
        --profile-format V0_1_5_S # Select based on device and the preceding table.

# Install APK and the profile together
adb install-multiple appname-release.apk appname-release.dm

Per supportare le suddivisioni dell'APK, esegui i passaggi precedenti per l'estrazione del profilo una volta per APK. Al momento dell'installazione, passa ogni APK e il file .dm associato, assicurandoti che i nomi di APK e .dm corrispondano:

adb install-multiple appname-base.apk appname-base.dm \
appname-split1.apk appname-split1.dm

Verifica

Per verificare che il profilo sia installato correttamente, puoi utilizzare la procedura descritta in Misurare manualmente i miglioramenti dell'app.

Eseguire il dump dei contenuti di un profilo binario

Per eseguire l'introspezione dei contenuti di una versione binaria compatta di un profilo di riferimento, utilizza l'opzione Profgen-cli dumpProfile:

Usage: profgen dumpProfile options_list
Options:
    --profile, -p -> File path to the binary profile (always required)
    --apk, -a -> File path to apk (always required) { String }
    --map, -m -> File path to name obfuscation map { String }
    --strict, -s [true] -> Strict mode
    --output, -o -> File path for the HRF (always required) { String }
    --help, -h -> Usage info

dumpProfile ha bisogno dell'APK perché la rappresentazione binaria compatta immagazzina solo gli offset DEX e, pertanto, ne ha bisogno per ricostruire i nomi di classi e metodi.

La modalità rigorosa è attiva per impostazione predefinita ed esegue un controllo di compatibilità del profilo con i file DEX nell'APK. Se stai cercando di eseguire il debug di profili generati da un altro strumento, potresti riscontrare errori di compatibilità che ti impediscono di eseguire il dump per le indagini. In questi casi, puoi disabilitare la modalità più restrittiva con --strict false. Tuttavia, nella maggior parte dei casi, dovresti mantenere attiva la modalità più restrittiva.

Una mappa di offuscamento è facoltativa. Se fornita, aiuta a rimappare i simboli offuscati alle relative versioni leggibili per facilitarne l'utilizzo.