iOS-Trace: Otimização Autônoma de Desempenho de Aplicativos
iOS-Trace é um mecanismo de otimização de desempenho em malha fechada para aplicativos iOS e iPadOS rodando em dispositivos físicos iPhone/iPad e simuladores iOS locais (SwiftUI, UIKit, Metal, CoreAudio / AVAudioEngine e rede URLSession).
O objetivo central é eliminar a interação manual com o Instruments. Um agente de IA pode diagnosticar autonomamente, localizar gargalos, implementar alterações de código, re-testar com análise diferencial e iterar até que as metas de desempenho sejam comprovadas com dados empíricos.
+-------------------------------------------------------------------------+
| O Ciclo de Otimização Autônoma |
| |
| 1. Alinhamento de Metas ──> 2. Traço Diagnóstico ──> 3. Correção Alvo |
| ^ │ |
| │ ▼ |
| └────── Iterar se a Meta Não For Atingida <── 4. Verificação |
+-------------------------------------------------------------------------+
Fase 1: Alinhamento de Metas do Usuário (Questionário Pré-Voo)
Antes de modificar código ou coletar traços em dispositivos móveis, o agente deve alinhar com o usuário os alvos de otimização e critérios de sucesso.
Interação com Ferramenta Modal vs. Chat
- Se sua plataforma de agente fornecer uma ferramenta modal interativa (por exemplo,
ask_question, diálogos de entrada ou listas de opções selecionáveis), invoque-a para apresentar essas escolhas de forma limpa ao usuário. - Se nenhuma ferramenta modal estiver disponível, pergunte diretamente ao usuário na conversa com opções estruturadas e valores recomendados concretos.
Perguntas a Fazer ao Usuário
-
Objetivo Primário da Otimização:
- Opção A: Reduzir drenagem da bateria, utilização de CPU e throttling térmico.
- Opção B: Reduzir pegada de memória, picos transitórios de alocação ou prevenir crashes Jetsam OOM.
- Opção C: Eliminar engasgos de quadros da interface e animações descartadas (Hitches em ProMotion 120Hz).
- Opção D: Acelerar o tempo de inicialização a frio do aplicativo móvel.
- Opção E: Otimizar sobrecarga de rádio de rede e eficiência de requisições em lote.
-
Metas Específicas de Desempenho (Fornecer Padrões Recomendados)
- Metas de Bateria e CPU
- Alvo de Linha Base em Repouso: < 15 M/s instruções, Impacto de CPU < 0.3.
- Alvo de Carga de Trabalho Ativa: < 80 M/s instruções (ou especificar: reduzir em 30% - 50%).
- Metas de Memória e Jetsam
- RAM Residente Máxima: Limite em < 150 MB (utilitários padrão) ou < 300 MB (aplicativos de mídia/interativos ricos).
- Taxa de Eventos de Alocação: < 400 eventos/seg durante interação em estado estável.
- Vazamentos de Memória: Exatamente 0 vazamentos persistentes.
- Metas de Suavidade da Interface e Taxa de Quadros
- Taxa de Engasgo (Hitch Ratio): < 5.0 ms/s (aceitável), < 1.0 ms/s (fluido / grau ProMotion 120Hz).
- Duração Máxima do Engasgo: < 16.6ms (60Hz) ou < 8.33ms (120Hz).
- Metas de Tempo de Inicialização
- Tempo até o Primeiro Quadro: < 400 ms (excelente), < 800 ms (aceitável).
- Metas de Rede e Rádio
- Sobrecarga de Rádio: Agrupar pings periódicos em requisições únicas em lote para evitar energia de espera da cauda do rádio.
- Metas de Bateria e CPU
-
Cenário de Benchmark do Usuário
- Pergunte ao usuário qual tela específica, interação do usuário, dispositivo físico ou simulador deve ser usado como benchmark.
Uma vez que as metas sejam confirmadas, prossiga para a Fase 2.
Escopo e Pré-requisitos
- Plataformas alvo: Aplicativos iOS e iPadOS rodando em dispositivos físicos iPhone/iPad conectados via USB ou rede local, ou simuladores iOS locais. (Para aplicativos desktop macOS, use macOS-Trace).
- Sistema host: macOS 12+ rodando em Apple Silicon ou Intel Mac com Xcode completo ou Xcode Command Line Tools (
xcode-select -p,xcrun xctrace version). - Prontidão do dispositivo:
- O iPhone/iPad físico deve estar desbloqueado e confiável para o Mac host.
- O dispositivo deve aparecer sob
== Devices ==(não== Devices Offline ==) ao executarxcrun xctrace list devices. - O bloqueio automático deve ser configurado como "Nunca" ou a tela mantida ativa durante as gravações para evitar que o iOS suspenda processos em segundo plano.
- Python: Python 3.8+ no Mac host (usa apenas a biblioteca padrão; zero dependências pip externas).
- Entitlements do processo: Builds de depuração ou builds provisionados para desenvolvedor com entitlement
get-task-allowsão necessários para--attach <PID>.
Regras para Agentes
Siga estas regras inegociáveis durante a perfilagem automatizada:
- Verificar estado de conexão do dispositivo: Sempre execute
xcrun xctrace list devicesantes de gravar. Nunca tente gravar contra um dispositivo listado sob== Devices Offline ==. - Prevenir bloqueio de tela e background: Se o dispositivo iOS bloquear ou retornar à tela inicial, o iOS suspende ou limita o processo, produzindo medições inválidas. Mantenha o dispositivo acordado e o aplicativo em primeiro plano.
- Estabelecer uma linha base primeiro: Nunca grave apenas a carga de trabalho ativa. Sempre capture uma execução de linha base em repouso (aplicativo em primeiro plano, tela do dispositivo ligada, carga de trabalho pausada) antes de gravar o estado ativo. Calcule:
Delta = Ativo - Linha Base. - Usar parâmetros de teste iguais: Compare execuções com durações de amostra idênticas (padrão:
60s), estados de bateria do dispositivo idênticos (evite perfilagem com bateria abaixo de 20% ou em Modo de Baixa Energia) e dados de entrada de teste idênticos. - Nenhuma dependência Python de terceiros: Todos os scripts inclusos (
scripts/compare_elements.py,scripts/parse_power.py,scripts/top_categories.py) usam apenas a biblioteca padrão do Python 3. - Salvar saídas em
/tmp/ios-traces/: Armazene todos os pacotes.tracee exportações.xmlem/tmp/ios-traces/com nomes de arquivo com timestamp e tag do cenário. - Proteger o orçamento de contexto da conversa: Arquivos de traço e documentos XML exportados brutos podem ter dezenas ou centenas de megabytes. Nunca despeje saídas
.tracebrutas, árvores de chamada completas ou XML de Alocações não processadas no contexto da conversa do agente. Sempre use os scripts Python inclusos para transmitir, filtrar, classificar e resumir os dados antes de ler. - Focar nos gargalos principais: Não espalhe micro-otimizações por dezenas de funções utilitárias inocentes. Primeiro, faça a perfilagem para confirmar o contribuidor dominante (por exemplo, instâncias de superfície redundantes, reavaliações de timer de alta frequência, E/S sem buffer) e concentre os esforços de otimização exclusivamente nessa causa raiz.
- Nunca alterar silenciosamente UI, efeitos visuais ou comportamento central: Se um gargalo de desempenho envolver fidelidade visual (como desfoque/materiais, animações de quadros, sombras, transições de layout) ou comportamento essencial do software:
- Não remova ou rebaixe unilateralmente o recurso visual.
- Peça formalmente permissão ao usuário primeiro (usando um prompt interativo ou mensagem explícita no chat).
- Articule claramente o trade-off: Descreva a mudança visual antes e depois, explique por que o recurso consome recursos e apresente o ganho de desempenho concreto esperado (por exemplo, "Desabilitar sombra dinâmica e desfoque nas visualizações de cartão reduzirá o impacto médio da GPU de 1.8 para 0.2 e eliminará engasgos do ProMotion 120Hz").
- Limpar artefatos de gravação: Cada gravação
xctraceescreve vários GB de traços de kernel transitórios (instruments*.ktrace) e um cache da CLI do Instruments (C/com.apple.dt.InstrumentsCLI) na pasta de temporários do sistema ($TMPDIR). Oscripts/run_trace.shos remove automaticamente na saída (tanto em sucesso quanto em falha). Ao executarxctracediretamente, limpe-os você mesmo antes de concluir:find "${TMPDIR:-/tmp}" -maxdepth 1 -type f -name 'instruments*.ktrace' -delete 2>/dev/null || true
O Protocolo de Otimização em 4 Fases
Fase 2: Perfilagem Diagnóstica e Atribuição
Antes de escrever código, meça o estado atual no dispositivo e isole a causa raiz:
# 1. Confirme que o dispositivo alvo está online e desbloqueado (verificação opcional;
# run_trace.sh detecta automaticamente o primeiro iPhone/iPad conectado quando --device é omitido)
xcrun xctrace list devices
BUNDLE_ID="com.example.MyApp"
# SKILL_DIR = diretório de instalação deste skill (ajuste se instalado em outro lugar)
SKILL_DIR="$HOME/.claude/skills/ios-trace"
# 2. Grave 60s de linha base em repouso (dispositivo desbloqueado, app em primeiro plano, carga pausada)
"$SKILL_DIR/scripts/run_trace.sh" \
--bundle-id "$BUNDLE_ID" \
--template power \
--duration 60s \
--label "01-baseline"
# 3. Dispare a carga de trabalho alvo no app, grave o estado ativo
"$SKILL_DIR/scripts/run_trace.sh" \
--process "MyApp" \
--template power \
--duration 60s \
--label "02-pre-opt"
# 4. Calcule o delta pré-otimização
python3 "$SKILL_DIR/scripts/compare_elements.py" \
/tmp/ios-traces/01-baseline-power.xml:"Linha Base em Repouso" \
/tmp/ios-traces/02-pre-opt-power.xml:"Ativo Pré-Otimização"
Use os templates especializados para atribuir o gargalo:
- Execute
--template timepara isolar funções de hotspots na árvore de chamadas em threads de trabalho. - Execute
--template alloccomscripts/top_categories.pypara identificar alocações excessivas que causam pressão de memória. - Execute
--template hitchesdurante a rolagem para isolar atrasos de renderização vs. commit em telas ProMotion. - Execute
--template networkpara detectar despertares de rádio contínuos não agrupados.
Fase 3: Modificação de Código Direcionada
Aplique correções mínimas e cirúrgicas com base nos achados:
- Picos de Memória e Jetsam: Adote downsampling para imagens de alta resolução com
CGImageSourceCreateThumbnailAtIndexem vez de carregarUIImageem tamanho completo. - Engasgos ProMotion: Remova sombras complexas e passes de blending offscreen; descarregue cálculos pesados de layout de visualização da thread principal.
- Sobrecarga de Energia de Rádio: Agrupe requisições de rede periódicas em rajadas de payload unificadas para eliminar energia de espera da cauda do rádio.
- Áudio em Tempo Real: Garanta zero alocações de heap em callbacks de renderização do CoreAudio (
AVAudioEngineou RemoteIO).
Recompile o aplicativo e implante no dispositivo.
Fase 4: Re-Teste, Revisão Quantitativa e Portão de Decisão
Reexecute a perfilagem sob condições idênticas e avalie o delta:
# 1. Grave a carga de trabalho ativa pós-otimização
"$SKILL_DIR/scripts/run_trace.sh" \
--process "MyApp" \
--template power \
--duration 60s \
--label "03-post-opt"
# 2. Compare Pré-Otimização vs. Pós-Otimização contra a Linha Base
python3 "$SKILL_DIR/scripts/compare_elements.py" \
/tmp/ios-traces/01-baseline-power.xml:"Linha Base em Repouso" \
/tmp/ios-traces/02-pre-opt-power.xml:"Ativo Pré-Otimização" \
/tmp/ios-traces/03-post-opt-power.xml:"Ativo Pós-Otimização"
Exemplo de Saída de Decisão:
Cenário Seg Média CPU Máx CPU Tela Média GPU Instr Totais Instr M/s WiFi Tx/Rx
===============================================================================================================
Linha Base em Repouso 60 0.12 0.60 0.05 0.00 0.85G 14.2 0.0/0.0MB
Ativo Pré-Otimização 60 2.40 4.80 1.10 1.80 15.60G 260.0 14.2/1.8MB
Ativo Pós-Otimização 60 0.55 1.10 0.15 0.20 4.20G 70.0 2.1/0.4MB
---------------------------------------------------------------------------------------------------------------
Diferencial vs. Linha Base [Linha Base em Repouso]:
Ativo Pré-Otimização +245.8 M/s instruções, Delta Médio de CPU +2.28, Delta Tx WiFi +14.20MB
Ativo Pós-Otimização +55.8 M/s instruções, Delta Médio de CPU +0.43, Delta Tx WiFi +2.10MB
Delta de Otimização (Pós vs. Pré):
Throughput de instruções: -73.1% (70.0 vs. 260.0 M/s)
Impacto Médio de CPU: -77.1% (0.55 vs. 2.40)
Impacto Médio de GPU: -88.9% (0.20 vs. 1.80)
Tráfego de Rádio WiFi: -85.2% (2.1MB vs. 14.2MB)
Lógica do Portão de Decisão:
- Meta Atingida: Apresente a tabela de comparação empírica ao usuário e conclua.
- Meta Não Atingida: Mantenha a otimização anterior, isole o próximo hotspot restante e repita as Fases 3 e 4.
Limpeza Pós-Relatório: Após o usuário aceitar o relatório final de otimização, exclua os pacotes .trace acumulados em /tmp/ios-traces/ (cada um pode ter dezenas de GB), a menos que o usuário peça explicitamente para mantê-los. A tabela de comparação finalizada e as exportações .xml mostradas no relatório são evidências suficientes.
Comandos CLI Diretos
Se executar xctrace diretamente sem run_trace.sh:
Gravar
# Anexar ao app em execução no dispositivo
xcrun xctrace record \
--device <DEVICE_UDID> \
--template 'Power Profiler' \
--time-limit 60s \
--output /tmp/ios-traces/power.trace \
--attach <PID>
# Inicialização a frio do app no dispositivo
xcrun xctrace record \
--device <DEVICE_UDID> \
--template 'Time Profiler' \
--time-limit 30s \
--output /tmp/ios-traces/launch.trace \
--launch -- com.example.MyApp <LaunchArgs>
Exportar
# Exportar tabela de Impacto de Energia (instruções de CPU, energia, GPU, Tela, WiFi/Celular)
xcrun xctrace export \
--input /tmp/ios-traces/power.trace \
--xpath "/trace-toc/run[@number='1']/data/table[@schema='ProcessSubsystemPowerImpact']" \
> /tmp/ios-traces/power.xml
# Exportar tabela de resumo de Alocações
xcrun xctrace export \
--input /tmp/ios-traces/alloc.trace \
--xpath "/trace-toc/run[@number='1']/data/table[@schema='all-allocations-summary']" \
> /tmp/ios-traces/alloc.xml
Referência de Templates
Templates do Instruments suportados no iOS via scripts/run_trace.sh e xctrace headless:
Computação, Bateria e Energia
| Template | Nome Curto | Métricas Alvo e Esquema de Exportação | Caso de Uso |
|---|---|---|---|
Power Profiler | power | Instruções/seg (M/s), impactos de energia CPU/GPU/Tela/WiFi/Celular (ProcessSubsystemPowerImpact). | Drenagem abrangente de bateria, throttling térmico e benchmarking A/B. |
Time Profiler | time | Pesos de amostra de CPU por thread, hotspots de árvore de chamadas, métodos de bloqueio da thread principal. | Alta utilização de CPU, threads de trabalho descontroladas e caminhos de funções quentes. |
CPU Counters | cpu | Contagens de ciclos de CPU, falhas de cache L1/L2, contagens de branches, uso de unidade NEON. | Análise de desempenho computacional de baixo nível, gargalos SIMD/NEON. |
Memória
| Template | Nome Curto | Métricas Alvo e Esquema de Exportação | Caso de Uso |
|---|---|---|---|
Allocations | alloc | Contagens e tamanhos totais de alocações vivas, eventos de alocação/liberação por tipo (all-allocations-summary, all-heap-summary). | Picos de memória, vazamentos, thrashing de alocação, pressão Jetsam. |
Leaks | leaks | Instâncias e gráficos de referência de vazamento, blocos de memória não liberados. | Verificação de vazamentos de memória persistentes (alvo: zero). |
VM Tracker | vm | Estatísticas de dirty memory, footprint residente, compressão, mapeamentos de VM, dirty por categoria/dirty size. | Otimização detalhada de footprint de memória e pressão de compressão. |
Tela e Animação
| Template | Nome Curto | Métricas Alvo e Esquema de Exportação | Caso de Uso |
|---|---|---|---|
Core Animation | hitches | Taxa de engasgo (Hit Rate), Duração de engasgo, atrasos de renderização vs. commit, utilização de GPU (esquema CoreAnimationFramesPerSecond). | Animação de interface, rolagem suave, desempenho 120Hz ProMotion. |
Metal System Trace | metal | Tempo de GPU, pipeline de renderização, compilações de shader, sincronização CPU/GPU, utilização de memória de textura. | Otimização de renderização Metal, gargalos de GPU. |
Rede
| Template | Nome Curto | Métricas Alvo e Esquema de Exportação | Caso de Uso |
|---|---|---|---|
Network | network | Tráfego WiFi/Celular tx/rx, destinos de conexão, padrão de rajada de rádio, estado de cauda de rádio (ProcessNetworkFlows). | Sobrecarga de rádio, agrupamento de requisições, eficiência de rede. |
Áudio
| Template | Nome Curto | Métricas Alvo e Esquema de Exportação | Caso de Uso |
|---|---|---|---|
Audio | audio | Utilização do CoreAudio, latência de renderização, estatísticas de buffer de áudio, alocações de heap em callbacks. | Otimização de áudio em tempo real, eliminação de alocações de heap em callbacks do CoreAudio. |
Estrutura de Scripts (dentro do diretório de instalação do skill)
scripts/
├── run_trace.sh # Wrapper para gravação e exportação do xctrace
├── compare_elements.py # Combina múltiplas exportações XML processa em tabela diferencial
├── parse_power.py # Analisa dados de energia/CPU por thread e processo do XML
├── top_categories.py # Analisa dados de alocações e classifica por tipo de criação
└── stackshot_parser.py # (Opcional) Analisa arquivos de relatório de sistema para sinais de pressão Jetsam
Solução de Problemas
xcrun xctrace record falha sem mensagem de erro
Adicione --no-prompt e --show-build para suprimir prompts de login:
xcrun xctrace record --no-prompt --device <UDID> --template power --time-limit 30s --output /tmp/ios-traces/test.trace --launch -- com.example.MyApp
Dispositivo não aparece em xcrun xctrace list devices
- Desconecte e reconecte o cabo USB.
- No dispositivo:
Settings > Developer > Enable Developer ModeeSettings > Developer > Enable UI Automation. - No Mac:
sudo killall -STOP -c usbd(reinicia o daemon USB) e tente novamente. - Se estiver usando rede local: verifique se ambos os dispositivos estão na mesma rede e que "Connect via network" está ativo em
Window > Devices and Simulatorsno Xcode.
Erro "Failed to attach to process"
- O binário do aplicativo deve ser assinado com o entitlement
get-task-allow, o que requer um build de depuração ou provisioning profile de desenvolvimento. - Para Simulator: garanta que o aplicativo esteja rodando no simulador alvo antes de anexar.
Simulador não consegue gravar dados de energia
O template Power Profiler só funciona em dispositivos físicos. Use Energy Log ou apenas o template Time Profiler para Simulator.
Nota de Compatibilidade
iOS-Trace foi desenvolvido e testado com:
- Xcode 15.x
- macOS Sonoma 14.x / Sequoia 15.x
- Dispositivos iOS 17.x / 18.x
- Todos os scripts operam sem dependências pip no Python 3.8+ da Apple.
Para aplicativos macOS desktop, consulte macOS-Trace.