dev/perf-runtime-telemetry-hot-path (#13)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #13 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #13.
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":26,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":27,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
|
||||
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
@@ -9,7 +9,7 @@
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"open","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-04-10","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0005","file":"workflow/decisions/DEC-0005-perf-push-based-telemetry-model.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0005","file":"workflow/plans/PLN-0005-perf-push-based-telemetry-implementation.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0026","file":"lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
id: LSN-0026
|
||||
ticket: perf-runtime-telemetry-hot-path
|
||||
title: Push-based Telemetry Model
|
||||
created: 2026-04-10
|
||||
tags: [performance, telemetry, atomics]
|
||||
---
|
||||
|
||||
# Push-based Telemetry Model
|
||||
|
||||
The PROMETEU telemetry system evolved from an on-demand scan model (pull) to an incremental counter model (push), aiming to minimize the impact on the runtime's hot path.
|
||||
|
||||
## The Original Problem
|
||||
|
||||
Previously, at every host tick, the runtime requested memory usage information from the asset banks. This resulted in:
|
||||
- $O(n)$ scans over resource maps.
|
||||
- Multiple read lock acquisitions in every tick.
|
||||
- Unnecessary overhead on handheld hardware, where every microsecond counts.
|
||||
|
||||
## The Solution: Push Model with Atomics
|
||||
|
||||
The implemented solution uses `AtomicUsize` in drivers and the VM to maintain the system state in real-time with $O(1)$ read and write cost:
|
||||
1. **Drivers (Assets):** Atomic counters in each `BankPolicy` are updated during `load`, `commit`, and `cancel`.
|
||||
2. **VM (Heap):** A `used_bytes` counter in the `Heap` struct tracks allocations and deallocations (sweep).
|
||||
3. **System (Logs):** The `LogService` tracks log pressure emitted in each frame.
|
||||
|
||||
## Two Levels of Observability
|
||||
|
||||
To balance performance and debugging, the collection was divided:
|
||||
- **Frame Snapshot (Always):** Automatic capture at the end of each logical frame. Irrelevant cost ($O(1)$). Serves the `Certifier` and historical logs.
|
||||
- **Host Tick (On-Demand):** Detailed collection in every tick only occurs if `inspection_active` is enabled (e.g., F1 Overlay on).
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
- **Trigger Decoupling:** We should not use the `Certifier` state to enable visual debugging features (like the overlay), as they have different purposes and costs.
|
||||
- **Eventual Consistency is Sufficient:** For telemetry metrics, it is not necessary to lock the system to obtain an exact value every nanosecond. Relaxed atomic reading is sufficient and much more performant.
|
||||
- **Cost Isolation:** Moving the aggregation logic to the driver simplifies the runtime and ensures that the telemetry cost is paid only during state mutations, rather than repeatedly during stable execution.
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
id: AGD-0007
|
||||
ticket: perf-runtime-telemetry-hot-path
|
||||
title: Agenda - [PERF] Runtime Telemetry Hot Path
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: []
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Runtime Telemetry Hot Path
|
||||
|
||||
## Problema
|
||||
|
||||
O runtime cobra telemetria de asset bank no caminho quente de todo host tick.
|
||||
|
||||
Hoje, `tick()` consulta `bank_info()` para `gfx` e `audio` mesmo quando nenhum logical frame foi fechado. O custo de observabilidade acaba sendo pago continuamente pela execucao normal.
|
||||
|
||||
## Dor
|
||||
|
||||
- CPU e locks sao gastos em todos os ticks, nao apenas quando a metrica muda.
|
||||
- hardware barato sofre mais com trabalho pequeno e repetitivo do que com picos raros.
|
||||
- overlay, stats e certifier acabam puxando custo estrutural para o core do runtime.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L167)
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L618)
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Remover varredura e agregacao lock-heavy do hot path do tick sem perder observabilidade util.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Modelo de metrica.
|
||||
Decidir o que passa a ser contador incremental e o que continua sendo snapshot sob demanda.
|
||||
|
||||
2. Frequencia de coleta.
|
||||
Decidir se atualizacao acontece:
|
||||
- no fechamento do logical frame;
|
||||
- apenas com overlay/debug ativo;
|
||||
- por amostragem periodica;
|
||||
- por evento de mutacao (`load`, `commit`, `cancel`).
|
||||
|
||||
3. Responsabilidade da agregacao.
|
||||
Delimitar se a verdade dos bytes/slots fica:
|
||||
- no `AssetManager`;
|
||||
- no runtime;
|
||||
- em uma camada propria de telemetry cache.
|
||||
|
||||
4. Garantia de consistencia.
|
||||
Decidir qual grau de defasagem e aceitavel para handheld barato:
|
||||
- exato em tempo real;
|
||||
- eventual por frame;
|
||||
- eventual por tick de debug.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. O certifier realmente precisa de snapshot de bank a cada tick?
|
||||
2. O overlay pode ler uma versao resumida da telemetria em vez de recalcular tudo?
|
||||
3. Vale manter caminho "preciso" so para testes/debug e caminho "barato" para runtime normal?
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../specs/10-debug-inspection-and-profiling.md`
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- metrica incremental vs snapshot;
|
||||
- ponto canonico de atualizacao da telemetria;
|
||||
- custo maximo aceitavel no hot path do tick;
|
||||
- comportamento de overlay/certifier sobre dados defasados.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user