82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
---
|
|
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.
|