Comandos de depuración para la generación de perfiles locales

Cuando pruebes tu integración de ProfilingManager de forma local, es posible que las solicitudes se limiten por el límite de frecuencia o que los seguimientos en segundo plano no estén activos cuando pruebes los activadores. Usa los comandos de adb de esta página para inhabilitar la limitación, extraer perfiles, retener seguimientos sin editar, activar capturas y, además, inspeccionar el estado del servicio en un dispositivo de prueba.

Inhabilita el limitador de frecuencia

Para inhabilitar los limitadores de frecuencia del sistema y del proceso de la app para las solicitudes de requestProfiling durante las pruebas locales, ejecuta el siguiente comando de device_config:

adb shell device_config put profiling_testing rate_limiter.disabled true

Cuando termines de realizar las pruebas, restablece la marca:

adb shell device_config delete profiling_testing rate_limiter.disabled

Nota: rate_limiter.disabled solo se aplica a las llamadas de requestProfiling controladas por la app. Cuando pruebes los activadores de forma local, configura system_triggered_profiling.testing_package_name para forzar un registro continuo en segundo plano y omitir el limitador de frecuencia a nivel del sistema, como se muestra en Forzar la habilitación de los registros en segundo plano para probar los activadores.

Cómo extraer perfiles con ADB

Para inspeccionar un perfil ocultado de forma local en un dispositivo con acceso raíz, ejecuta adb pull con la ruta de acceso que muestra getResultFilePath:

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

Nota: Si no tienes acceso con permisos de administrador, puedes configurar ProfilingManager para conservar los perfiles en /data/misc/perfetto-traces/profiling/, a los que se puede acceder con adb pull en todos los tipos de compilación en Android 16 (nivel de API 36) y versiones posteriores. Consulta Conserva los resultados temporales y sin ocultar.

Conservar los resultados temporales y sin ocultar

Cuando pruebes la generación de perfiles de forma local, puedes conservar los resultados en el directorio temporal en /data/misc/perfetto-traces/profiling/. Comparar un registro del sistema sin ocultar con su contraparte ocultada te ayuda a comprender qué datos se descartan durante el ocultamiento.

La forma en que se retienen los resultados temporales y sin ocultar depende de la versión de Android que ejecute tu dispositivo:

• Android 16 (nivel de API 36) y versiones posteriores: Puedes conservar los resultados sin ocultar (cuando corresponda) y ocultados en el directorio temporal, que se expandió en Android 16 para que se pueda acceder a él con adb pull en todos los tipos de compilación sin acceso raíz (mientras que Android 15 requiere acceso raíz para leer /data/misc/perfetto-traces/profiling/). Para evitar que el sistema borre los resultados temporales, ejecuta el siguiente comando:

  adb shell device_config put profiling_testing delete_temporary_results.disabled true
  

• Android 15 (nivel de API 35): En el directorio temporal, solo puedes conservar el resultado sin ocultar, al que se puede acceder a través de adb solo en las compilaciones con acceso de administrador. (Tu app aún recibe el perfil ocultado en su propio directorio /data/user/0/<app>/files/profiling/, que el código de tu app puede leer o copiar en cualquier compilación, aunque extraer directamente de /data/user/0/... con adb pull requiere acceso raíz o adb shell run-as <app> en una compilación depurable). Para evitar que el sistema borre los seguimientos sin ocultar, ejecuta el siguiente comando:

  adb shell device_config put profiling_testing delete_unredacted_trace.disabled true
  

Después de capturar un perfil, extrae el archivo retenido del directorio temporal:

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

En estos comandos, <trace-name> es el nombre de archivo base (sin extensión) de la ruta de acceso que devuelve ProfilingResult.getResultFilePath, y la copia del seguimiento del sistema sin ocultar agrega -unredacted a la extensión .perfetto-trace. Para obtener detalles sobre la estructura del nombre de archivo y los valores de <profile-type-ext>, consulta Ubicaciones de archivos y formatos de nombres.

Nota: La retención de resultados temporales y sin ocultar está inhabilitada de forma predeterminada para conservar el almacenamiento del dispositivo y solo se diseñó para pruebas locales. Los registros del sistema sin ocultar usan más espacio de almacenamiento porque incluyen la actividad de los procesos de todo el sistema. Cuando termines de realizar las pruebas, vuelve a habilitar la eliminación automática:

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

Cómo forzar la habilitación de seguimientos en segundo plano para probar activadores

Debido a que los seguimientos en segundo plano del sistema se ejecutan en intervalos aleatorios en producción, puede ser difícil probar la generación de perfiles basada en activadores de forma local. Para forzar al sistema a ejecutar un seguimiento continuo en segundo plano y omitir el limitador de frecuencia a nivel del sistema para los activadores de tu app, establece system_triggered_profiling.testing_package_name:

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

Aún se aplica cualquier tiempo de espera por activador configurado con setRateLimitingPeriodHours. Como este modo se ejecuta de forma continua hasta que lo borras, quita la marca cuando termines de realizar las pruebas:

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

Comandos de depuración útiles

En Android 16 (nivel de API 36) y versiones posteriores con una versión reciente del módulo Profiling, puedes usar la herramienta cmd profiling_service en adb para habilitar el registro detallado, activar recopilaciones de perfiles on demand y probar activadores directamente desde la línea de comandos.

Nota: Es posible que existan opciones adicionales o que se agreguen con el tiempo. Ejecuta adb shell cmd profiling_service help para ver todos los comandos de depuración, las marcas y los detalles de uso disponibles.

Habilita el registro de depuración detallado

Para habilitar los registros detallados de ProfilingService en logcat y diagnosticar el manejo y la entrega de solicitudes, ejecuta el siguiente comando:

adb shell cmd profiling_service enable-logs true

Solicita una recopilación de perfiles on demand

Para iniciar una captura de perfil inmediata de un paquete específico desde la línea de comandos, ejecuta el siguiente comando:

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

En este comando, <profiling_type> es el valor de la constante de número entero de ProfilingManager (1 para un volcado de montón de Java, 2 para un perfil del montón, 3 para un muestreo de pila o 4 para un registro del sistema). El proceso de la app de destino debe estar en ejecución para los perfiles de memoria y pila, la solicitud está sujeta al limitador de frecuencia, a menos que esté inhabilitado, y el ProfilingResult completado se entrega solo a los objetos de escucha globales registrados con registerForAllProfilingResults.

Registra y simula activadores

Para registrar un activador o activar un evento de activador simulado para un paquete y verificar el manejo de la devolución de llamada del activador, ejecuta los siguientes comandos:

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

En estos comandos, <trigger_type> es el valor de la constante de número entero de ProfilingTrigger (por ejemplo, 1 para TRIGGER_TYPE_APP_FULLY_DRAWN, 2 para TRIGGER_TYPE_ANR o 7 para TRIGGER_TYPE_OOM). Cuando ejecutas add-trigger, se registra el activador con un tiempo de espera de 0 horas, lo que anula cualquier registro existente para ese tipo de activador. Para simular activadores que guarden una instantánea del seguimiento en segundo plano (como 1 o 2), se requiere un seguimiento en segundo plano activo (consulta Cómo forzar la habilitación de seguimientos en segundo plano para probar activadores).

Recopila el estado general de ProfilingManager

En Android 16 (nivel de API 36) y versiones posteriores con una versión reciente del módulo Profiling, puedes ejecutar dumpsys en profiling_service para diagnosticar problemas y, además, inspeccionar el estado actual de ProfilingManager:

adb shell dumpsys profiling_service

El resultado de dumpsys profiling_service solo tiene fines informativos y de depuración, y su formato está sujeto a cambios. Proporciona una instantánea del estado interno del servicio, que incluye lo siguiente:

• Estado de las limitaciones activas y del limitador de frecuencia.
• Configuraciones de dispositivos activos
• Son los activadores de apps registrados y sus períodos de inactividad con límite de frecuencia.
• Sesiones de generación de perfiles activas y en cola.
• Solicitudes de generación de perfiles recientes, activaciones de eventos y eventos de entrega de resultados.

Sugerencia: Para conservar un historial más largo de eventos recientes en el resultado de dumpsys durante sesiones de depuración extendidas, ejecuta adb shell cmd profiling_service enable-long-dumpsys true.