Creare e misurare manualmente i profili di riferimento

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

Definisci manualmente le regole del profilo

Puoi definire manualmente le regole del profilo in un'app o in un modulo della libreria creando un file denominato baseline-prof.txt nella directory src/main. Questa è la 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 da ottimizzare.

La sintassi di queste regole è un superset del formato del profilo ART leggibile (HRF) 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 il processo di scrittura delle regole.

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

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 di esempio di Compiler Explorer. Tieni presente che Compiler Explorer supporta solo il formato del profilo ART leggibile (HRF), pertanto i caratteri jolly non sono supportati.

Sintassi delle regole

Queste regole assumono una delle due forme per scegliere come target i metodi o le classi:

[FLAGS][CLASS_DESCRIPTOR]->[METHOD_SIGNATURE]

Una regola di classe utilizza il seguente pattern:

[CLASS_DESCRIPTOR]

Per una descrizione dettagliata, consulta la tabella seguente:

Sintassi	Descrizione
FLAGS	Rappresenta uno o più caratteri H, S e P per indicare se questo metodo deve essere contrassegnato come Hot, Startup o Post Startup in relazione al tipo di avvio. Un metodo con il flag H indica che si tratta di un metodo "hot", ovvero che viene chiamato molte volte durante il ciclo di vita dell'app. Un metodo con il flag S indica che si tratta di un metodo chiamato durante l'avvio. Un metodo con il flag P indica che si tratta di una chiamata al metodo dopo l'avvio. Una classe presente in questo file indica che viene utilizzata durante l'avvio e deve essere pre-allocata nell'heap per evitare il costo del caricamento della classe. Il compilatore ART utilizza varie strategie di ottimizzazione, come la compilazione AOT di questi metodi e l'esecuzione di ottimizzazioni del layout nel file AOT generato.
CLASS_DESCRIPTOR	Descrittore della classe del metodo scelto come target. Ad esempio, androidx.compose.runtime.SlotTable ha un descrittore di Landroidx/compose/runtime/SlotTable;. La L viene anteposta qui in base al formato Dalvik Executable (DEX).
METHOD_SIGNATURE	Firma del metodo, inclusi il nome, i tipi di parametri e i tipi restituiti del metodo. Ad esempio: // LayoutNode.kt fun isPlaced():Boolean { // ... } su LayoutNode ha la firma isPlaced()Z.

Questi pattern possono contenere caratteri jolly per fare in modo che una singola regola comprenda più metodi o classi. Per un'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 essere il seguente:

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

Tipi supportati nelle regole del profilo di riferimento

Le regole del profilo di riferimento supportano i seguenti tipi. Per maggiori dettagli su questi tipi, consulta il formato Dalvik Executable (DEX).

Carattere	Tipo	Descrizione
B	byte	Byte con segno
C	char	Punto di codice del carattere Unicode codificato in UTF-16
D	double	Valore in virgola mobile a precisione doppia
F	float	Valore in virgola mobile a precisione singola
I	int	Numero intero
J	lungo	Numero intero lungo
S	video breve	Short firmato
V	void	Vuoto
Z	boolean	Vero o falso
L (nome del corso)	riferimento	Un'istanza di un nome di classe

Inoltre, le librerie possono definire regole pacchettizzate in artefatti AAR. Quando crei un APK per includere questi elementi, le regole vengono unite, in modo simile all'unione dei 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 la compilazione AOT di un sottoinsieme specifico dell'app al momento dell'installazione su Android 9 (livello API 28) o Android 7 (livello API 24) quando si utilizza ProfileInstaller.

Raccogli 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 Critical User Journey. Sebbene consigliamo di utilizzare i macrobenchmark, potrebbe non essere sempre possibile. Ad esempio, se utilizzi un sistema di build non Gradle, non puoi utilizzare il plug-in Gradle per i profili di riferimento. In questi casi, puoi raccogliere manualmente le regole del profilo di riferimento. Questo è molto più semplice se utilizzi un dispositivo o un emulatore con API 34 e versioni successive. Sebbene sia ancora possibile con livelli API inferiori, richiede l'accesso root e devi utilizzare un emulatore che esegue un'immagine AOSP. Puoi raccogliere le regole direttamente seguendo questi passaggi:

1. Installa una versione di release della tua app su un dispositivo di test. Il tipo di build dell'app non deve essere ottimizzato per R8 e non deve essere abilitato al debug per acquisire un profilo che possa essere utilizzato dal sistema di build.
2. Disattiva l'installazione del profilo e chiudi l'app.

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

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

3. Reimposta la compilazione dell'app e cancella tutti i profili.

   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

4. Esegui l'app e naviga manualmente nei Critical User Journey per i quali vuoi raccogliere un profilo.

5. Attendi almeno cinque secondi per consentire la stabilizzazione dei profili.

6. Esegui l'azione di salvataggio e attendi il completamento. Se il tuo APK ha una dipendenza dalla libreria Jetpack Profile Installer, utilizzala per eseguire il dump dei profili:

   adb shell am broadcast -a androidx.profileinstaller.action.SAVE_PROFILE $PACKAGE_NAME/androidx.profileinstaller.ProfileInstallReceiver
   sleep 1 # wait 1 second
   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
   sleep 1 # wait 1 second
   adb shell am force-stop $PACKAGE_NAME

7. 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 attuale. 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

8. Utilizza adb per recuperare il profilo di cui è stato eseguito il dump dal dispositivo:

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

In questo modo, le regole del profilo generate vengono estratte e installate nel modulo dell'app. La volta successiva che crei l'app, il profilo Baseline viene incluso. Verifica questo aspetto seguendo i passaggi descritti in Problemi di installazione.

Misura manualmente i miglioramenti dell'app

Nota: per una maggiore stabilità e precisione, consigliamo di utilizzare Macrobenchmark per misurare l'impatto sulle prestazioni, in quanto può misurare ripetutamente in un loop, acquisire tracce per il debug delle prestazioni e aumentare l'affidabilità, ad esempio svuotando la cache del disco del sistema operativo.

Ti consigliamo vivamente di misurare i miglioramenti dell'app tramite il benchmarking. Tuttavia, se vuoi misurare i miglioramenti manualmente, puoi iniziare misurando l'avvio dell'app non ottimizzato 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"

Successivamente, esegui il sideload del profilo di riferimento.

Nota: questo flusso di lavoro è supportato solo su Android 9 (API 28) fino ad Android 11 (API 30). Per maggiori informazioni, consulta Comportamento di compilazione nelle varie versioni di Android.

# 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 questo 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 le prestazioni di avvio dell'app come prima, ma senza reimpostare lo stato compilato. Assicurati di non reimpostare lo stato di compilazione del 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"

Nota: per una maggiore stabilità e precisione, è consigliabile utilizzare Macrobenchmark per misurare l'impatto sulle prestazioni, in quanto può misurare ripetutamente in un loop, acquisire tracce per il debug delle prestazioni e aumentare l'affidabilità (ad esempio, svuotando la cache del disco del sistema operativo).

Profili di baseline e profgen

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

Profgen-cli aiuta con la compilazione, l'introspezione e la transpilazione dei profili ART, in modo che possano essere installati sui dispositivi Android indipendentemente dalla versione dell'SDK target.

Profgen-cli è un'interfaccia a riga di comando che compila l'HRF di un profilo di riferimento nel formato compilato. La CLI viene fornita anche nel repository cmdline-tools come parte 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, utilizza 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, utilizza 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 dell'HRF baseline-prof.txt.

Profgen-cli richiede anche il percorso della build di 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 formato 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 pacchettizzi 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

Nota: quando raggruppi il profilo nella cartella assets, scegli sempre il formato v0_1_0_p.

Quando scegli un formato del profilo, sono disponibili le seguenti opzioni:

Formato del profilo	Versione piattaforma	Livello API
v0_1_5_s	Android S+	31+
v0_1_0_p	Android P, Q e R	28-30
v0_0_9_omr1	Android O MR1	27
v0_0_5_o	Android O	26
v0_0_1_n	Android N	24-25

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

Mappe di offuscamento

Devi fornire la mappa di offuscamento solo se l'HRF utilizza simboli di origine. Se l'HRF viene generato da una build di release 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 tradizionalmente inviati a un dispositivo in uno dei seguenti modi.

Utilizza install-multiple con DexMetadata

Sui dispositivi con API 28 e versioni successive, il client Play scarica il payload APK e DexMetadata (DM) per una versione APK in fase di installazione. Il DM contiene le informazioni del 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 un comando simile al seguente:

adb install-multiple base.apk base.dm

Nota: il payload DM del profilo corretto viene inviato in base alla versione dell'SDK del dispositivo da cui viene effettuata la richiesta di download dell'APK. Play genera una tupla transcodificando i profili pacchettizzati come v0_1_0_p in ogni versione del profilo nota in uso per fornire la versione corretta.

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 assets o 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 dell'SDK del dispositivo di destinazione e lo copia nella directory cur del dispositivo (una directory di gestione temporanea specifica per il pacchetto per i profili ART sul dispositivo).

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

Nota: ProfileInstaller può eseguire il backporting dei profili ART fino ad Android N, anche se la distribuzione di Baseline Profile tramite Play utilizzando install-multiple è supportata solo su dispositivi Android P e versioni successive. Pertanto, è importante dichiarare una dipendenza dalla libreria ProfileInstaller quando utilizzi i profili Baseline.

Esegui il sideload di un profilo di baseline

Questa sezione descrive come installare un profilo di riferimento dato un APK.

Trasmetti 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 Google Play, anche se è presente in quasi tutti gli APK che utilizzano Compose. Questo perché le librerie possono fornire profili senza dichiarare una dipendenza da ProfileInstaller. L'aggiunta di una dipendenza in ogni libreria con un profilo viene applicata a partire da Jetpack.

Utilizza 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 includere la libreria ProfileInstaller nell'app.

Per farlo, 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 degli APK, esegui i passaggi precedenti per l'estrazione del profilo una volta per ogni APK. Al momento dell'installazione, passa ogni APK e il file .dm associato, assicurandoti che i nomi dell'APK e di .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 seguire i passaggi descritti in Misura manualmente i miglioramenti dell'app.

Esegui il dump dei contenuti di un profilo binario

Per esaminare i 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 memorizza solo gli offset DEX e, pertanto, ne ha bisogno per ricostruire i nomi di classi e metodi.

La modalità StrictMode è attiva per impostazione predefinita ed esegue un controllo di compatibilità del profilo con i file DEX nell'APK. Se stai tentando di eseguire il debug dei profili generati da un altro strumento, potresti riscontrare errori di compatibilità che ti impediscono di eseguire il dump per l'indagine. In questi casi, puoi disattivare la modalità StrictMode con --strict false. Tuttavia, nella maggior parte dei casi è consigliabile mantenere attiva la modalità StrictMode.

Una mappa di offuscamento è facoltativa; se fornita, aiuta a rimappare i simboli offuscati nelle loro versioni leggibili per facilitarne l'utilizzo.