[PERF] Runtime Telemetry Hot Path
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
id: DEC-0005
|
||||
title: "Decisão - [PERF] Modelo de Telemetria Push-based"
|
||||
status: closed
|
||||
created: 2026-03-27
|
||||
resolved: 2026-03-27
|
||||
agenda: AGD-0007
|
||||
tags: []
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
1. **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).
|
||||
2. **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`.
|
||||
3. **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.
|
||||
4. **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](../agendas/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.
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
id: PLN-0005
|
||||
title: "Plano - [PERF] Implementação de Telemetria Push-based"
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
origin_decisions:
|
||||
- DEC-0005
|
||||
tags: []
|
||||
---
|
||||
|
||||
# Plano - [PERF] Implementação de Telemetria Push-based
|
||||
|
||||
## Briefing
|
||||
|
||||
Este plano detalha as alterações técnicas para migrar o sistema de telemetria de um modelo de varredura $O(n)$ com locks para um modelo push-based com contadores atômicos $O(1)$. O objetivo é reduzir o overhead do hot path do runtime e adicionar visibilidade sobre a memória RAM (Heap) e volume de logs.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
* [DEC-0005 - [PERF] Modelo de Telemetria Push-based](../decisions/DEC-0005-perf-push-based-telemetry-model.md)
|
||||
|
||||
## Alvo
|
||||
|
||||
* `prometeu-drivers` (AssetManager)
|
||||
* `prometeu-vm` (Heap)
|
||||
* `prometeu-hal` (TelemetryFrame)
|
||||
* `prometeu-system` (LogService, VirtualMachineRuntime)
|
||||
* `prometeu-host-desktop-winit` (HostRunner)
|
||||
|
||||
## Escopo
|
||||
|
||||
1. **Contadores Atômicos:** Implementação de `AtomicUsize` nos subsistemas de assets, heap e logs.
|
||||
2. **Telemetry Frame:** Expansão da struct para incluir `heap_used`, `heap_max` e `logs_count`.
|
||||
3. **Lógica de Tick:** Refatoração do `tick.rs` para usar `inspection_active` e snapshots de fim de frame.
|
||||
4. **Sinalização do Host:** Integração do campo `inspection_active` com o acionamento do overlay F1.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
* Migração da renderização do overlay para o host nativo (será tratado em plano derivado da AGD-0012).
|
||||
* Telemetria de FileSystem IO ou Corrotinas.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Fase 1: Drivers e VM (Modelo Push)
|
||||
1. **`prometeu-drivers/src/asset.rs`:**
|
||||
- Adicionar contadores em `BankPolicy`.
|
||||
- Atualizar contadores em `load_internal`, `commit` e `cancel`.
|
||||
- Refatorar `bank_info()` para retornar os valores atômicos sem varredura.
|
||||
2. **`prometeu-vm/src/heap.rs`:**
|
||||
- Adicionar contador `used_bytes` na struct `Heap`.
|
||||
- Atualizar contador em `alloc()` e `free()`.
|
||||
3. **`prometeu-system/src/log.rs`:**
|
||||
- Adicionar contador `logs_count` (resetável por frame) no `LogService`.
|
||||
|
||||
### Fase 2: HAL e Runtime (Contrato e Lógica)
|
||||
1. **`prometeu-hal/src/telemetry.rs`:**
|
||||
- Adicionar `heap_used_bytes`, `heap_max_bytes` e `logs_count` na `TelemetryFrame`.
|
||||
2. **`prometeu-system/src/virtual_machine_runtime.rs`:**
|
||||
- Adicionar campo `public inspection_active: bool`.
|
||||
3. **`prometeu-system/src/virtual_machine_runtime/tick.rs`:**
|
||||
- Modificar `tick()` para coletar `bank_info` detalhado apenas se `inspection_active == true`.
|
||||
- Implementar a captura do snapshot consolidado no fechamento do logical frame.
|
||||
|
||||
### Fase 3: Host e Integração
|
||||
1. **`prometeu-host-desktop-winit/src/runner.rs`:**
|
||||
- Sincronizar o estado do campo `overlay_enabled` com `firmware.os.inspection_active`.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
* O sistema compila sem avisos de tipos inexistentes.
|
||||
* A telemetria de assets (`gfx`/`audio`) continua funcional no overlay F1.
|
||||
* Novos campos de Heap e Logs aparecem no log de performance do console.
|
||||
* O custo de telemetria no `tick` deve cair drasticamente quando o overlay estiver desligado (verificável via profiling).
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
* **Teste Unitário:** Criar teste em `asset.rs` para garantir que contadores batem com a realidade após sequências de carga e cancelamento.
|
||||
* **Teste de Regressão:** Garantir que o `certifier` continua detectando violações de bank no fim do frame.
|
||||
|
||||
## Riscos
|
||||
|
||||
* **Consistência Eventual:** Como os contadores são atômicos e não travam o sistema, pode haver uma defasagem momentânea durante um `commit` pesado; isto é aceitável conforme DEC-0005.
|
||||
Reference in New Issue
Block a user