[PERF] Runtime Telemetry Hot Path

This commit is contained in:
2026-04-10 08:59:02 +01:00
parent 5e80ea46b8
commit 63892dcfb9
16 changed files with 537 additions and 141 deletions
@@ -59,8 +59,30 @@ Remover varredura e agregacao lock-heavy do hot path do tick sem perder observab
## Open Questions de Arquitetura
1. O certifier realmente precisa de snapshot de bank a cada tick?
Não. O certifier aceita dados do fim do frame anterior, pois violações de limites de bank costumam ser persistentes entre frames.
2. O overlay pode ler uma versao resumida da telemetria em vez de recalcular tudo?
Sim. O `AssetManager` passará a prover uma struct `BankStats` pré-calculada via contadores atômicos.
3. Vale manter caminho "preciso" so para testes/debug e caminho "barato" para runtime normal?
Sim, mas a "precisão" será definida como "atualizado no último evento de mutação", o que já é suficiente para ambos os casos.
4. Como detectar o modo de depuração/inspeção de forma correta e desacoplada?
Através de um novo campo `inspection_active: bool` no `VirtualMachineRuntime`, controlado explicitamente pelo Host (ex: quando o Overlay F1 ou o Debugger remoto estão ativos). O `certifier` não deve ser usado para este propósito.
## Sugestao / Recomendacao
1. **Modelo de Métrica (Push-based):**
- Migrar de snapshot total $O(n)$ para contadores incrementais $O(1)$ no `AssetManager`.
- Utilizar `AtomicUsize` ou campos protegidos por Mutex simples para `used_bytes`, `inflight_bytes` e `slots_occupied`.
- Atualizar esses contadores apenas em eventos de mutação (`load`, `commit`, `cancel`).
2. **Frequência de Coleta (Dois Níveis):**
- **Básica (Sempre):** O Runtime deve atualizar `telemetry_current` no fechamento de cada logical frame (`FrameSync` ou `EndOfRom`). Isso garante dados para o `certifier` com custo $O(1)$.
- **Alta Frequência (Sob Demanda):** Manter atualização em todo host tick apenas se `inspection_active` for `true` (Overlay F1 visível ou Debugger conectado).
3. **Responsabilidade da Agregação (Centralizada):**
- O `AssetManager` é o dono da "verdade incremental". O Runtime consome um snapshot barato (struct POD) sem varredura de locks.
4. **Garantia de Consistência (Eventual):**
- Aceitar defasagem de até 1 frame lógico para métricas de asset bank.
## Dependencias
@@ -52,19 +52,22 @@ Isolar o overlay de debug do custo medido do console sem perder utilidade para d
## Open Questions de Arquitetura
1. O overlay precisa ser representativo do hardware final ou apenas ferramenta de desktop?
Não, como é HUD técnico, pode e deve ser renderizado pelo Host nativo para melhor legibilidade.
2. Vale um modo "perf puro" onde overlay nunca toca no framebuffer do console?
Sim. O isolamento garante que o `gfx` emulado esteja 100% livre para o jogo durante a medição.
3. O host deve oferecer toggles separados para stats, logs e overlay visual?
Sim. O `HostRunner` deve expor controles granulares via `inspection_active`.
4. Como melhorar a legibilidade e estética (Glyphs/Transparência)?
Migrar a renderização do HUD para o Host Nativo (Winit/Pixels), permitindo o uso de fontes TrueType (monospaced) nítidas e Alpha Blending real para transparência no fundo do painel.
## Dependencias
- `../specs/10-debug-inspection-and-profiling.md`
- `../specs/11-portability-and-cross-platform-execution.md`
## Criterio de Saida Desta Agenda
## Sugestao / Recomendacao
Pode virar PR quando houver decisao escrita sobre:
- onde o overlay e composto;
- politica de cache de texto/glyphs;
- como o custo do overlay aparece na telemetria;
- overhead maximo aceitavel em modo debug.
1. **Migração para Camada Host Nativa:** Renderizar o HUD de debug em uma surface separada ou via pipeline nativo do Host (depois do upscaling do framebuffer do console).
2. **Fontes TrueType (Mono):** Substituir os glyphs bitmapped rudimentares por uma fonte nativa de alta qualidade e nítida.
3. **Composição Alpha:** Permitir fundo semi-transparente para o overlay para não bloquear a visão do jogo.
4. **Acionamento Explícito:** Host deve gerenciar `inspection_active: true` no runtime apenas quando o HUD ou Debugger estiverem ativos.