Decisão - [PERF] Modelo de Telemetria Push-based

Status

Fechada (Closed) - Consensus reached. Implementation approved.

Contexto

O runtime atual (VirtualMachineRuntime::tick()) realiza a coleta de telemetria de asset banks (gfx e audio) em todos os host ticks. Essa coleta envolve a chamada de bank_info() no AssetManager, que executa uma varredura O(n) sobre mapas de recursos e adquire múltiplos locks de leitura. Em hardwares limitados (handhelds), esse custo repetitivo no caminho quente degrada a performance desnecessariamente, mesmo quando o sistema está estável ou em pausa.

Decisão

Modelo de Contadores no Driver e Runtime: O AssetManager, a Heap da VM e o LogService devem substituir a varredura/contagem total por contadores atômicos (used_bytes, inflight_bytes, slots_occupied, logs_count) para cada subsistema. Esses contadores serão atualizados incrementalmente (O(1)) em cada mutação (load, commit, alloc, free, log).
Snapshot Obrigatório de Fim de Frame: O runtime capturará o estado desses contadores (Banks, Heap e Logs) apenas uma vez por fechamento de frame lógico (FrameSync ou EndOfRom). Este snapshot será usado para alimentar a telemetry_last e o certifier.
Coleta sob Demanda (Inspection Mode): A coleta em cada host tick será reativada somente se o novo sinalizador inspection_active: bool do runtime for verdadeiro.
Desacoplamento do Certifier: A ativação do certifier não habilitará mais a telemetria detalhada em cada tick. O certifier será servido exclusivamente pelos snapshots de fim de frame lógico.

Rationale

Performance: Reduz o custo do tick do runtime de O(n) com locks para O(1) sem locks no modo normal.
Observabilidade: Mantém dados precisos para o overlay (via modo inspeção) e dados válidos para o certifier (via snapshot de frame).
Modularidade: Desacopla as necessidades de depuração (Overlay F1) das necessidades de validação normativa (Certifier).

Invariantes / Contrato

O AssetManager é a única fonte da verdade para o uso de memória de assets; o runtime não deve tentar calcular esses valores manualmente.
Contadores atômicos garantem que o runtime possa ler estatísticas de bancos sem travar mutações em andamento (consistência eventual).
A defasagem de até 1 frame lógico é aceitável para métricas de assets bank no modo de operação normal.

Impactos

Drivers: Necessidade de adicionar e gerenciar contadores no AssetManager.
Virtual Machine: Adicionar contador atômico de used_bytes na Heap.
Log Service: Adicionar contador incremental de logs emitidos no frame no LogService.
Runtime: Modificação no VirtualMachineRuntime para incluir o campo inspection_active e lógica condicional no tick().
Host: O host (ex: desktop-winit) deve agora sinalizar quando o overlay de depuração está ativo via inspection_active.

Referências

Agenda AGD-0007-perf-runtime-telemetry-hot-path.md
Spec 10-debug-inspection-and-profiling.md

Propagação Necessária

Atualizar o VirtualMachineRuntime para expor o campo inspection_active.
Atualizar o HostRunner para sinalizar inspection_active quando o overlay F1 for alternado.
Atualizar a struct TelemetryFrame para incluir campos de Heap Memory e Log count.

3.6 KiB Raw Blame History