Eve library

phase-160.md

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

Phase 160: Neith Engine Frame Profiler & Diagnostics — Unreal Insights / RenderDoc / PIX / NVIDIA Nsight / AMD Radeon GPU Profiler / Intel GPA / Xcode Instruments / Tracy / Optick Parity#

Closes the engine-profiling sovereignty gap. Phase 72.6 mentions telemetry with ~3 tasks. Phase 145 CI/CD collects DORA metrics. Phase 98 covers AI / service observability. None of these deliver a per-frame CPU + GPU + memory + network trace workbench that Unreal Insights, RenderDoc, PIX, Nsight, and Tracy provide — the toolchain an engine engineer cannot live without.

Sovereign replacement for Unreal Insights (Trace / Timing / Tasks / LLM / Rhi / CookerStats / Networking), Baldur Karlsson RenderDoc, Microsoft PIX on Windows, NVIDIA Nsight Graphics + Systems + Aftermath, AMD Radeon GPU Profiler + Radeon GPU Analyzer, Intel GPA, Apple Xcode Instruments GPU + Metal frame debugger, Tracy, Optick, Google Perfetto / systrace, and Superluminal.


160.1 @neith/profiler-capture — Tracing Backend#

  • 160.1.1 Instrumented-trace API (NEITH_PROFILE_SCOPE)
  • 160.1.2 Zero-overhead macro in release builds
  • 160.1.3 Ring-buffer per-thread lock-free writer
  • 160.1.4 Named scope / region with colour + category
  • 160.1.5 Counter / gauge / histogram events
  • 160.1.6 Async task / fiber / job linked events
  • 160.1.7 Source location + callstack capture
  • 160.1.8 Sample-profiling (stochastic) unified view
  • 160.1.9 GPU timestamp queries integrated
  • 160.1.10 Memory allocation track
  • 160.1.11 Frame boundary / vsync marker
  • 160.1.12 Cross-process streaming (dedicated-server + client)
  • 160.1.13 On-disk trace file format (versioned binary)
  • 160.1.14 Streaming to network viewer
  • 160.1.15 In-engine record / replay of trace

160.2 @neith/profiler-timing — Timing / Flamegraph View#

  • 160.2.1 Hierarchical timeline (thread swim-lanes)
  • 160.2.2 Zoom 1 ns ↔ whole session
  • 160.2.3 Flamegraph (bottom-up + top-down)
  • 160.2.4 Call-tree with inclusive / exclusive cost
  • 160.2.5 Search by scope name
  • 160.2.6 Group by category / thread / module
  • 160.2.7 Frame comparison (delta two frames)
  • 160.2.8 Critical-path highlight
  • 160.2.9 Tasks graph with dependencies
  • 160.2.10 Context switches
  • 160.2.11 Lock contention events
  • 160.2.12 CPU sample merger
  • 160.2.13 Budget overlay (16.67 ms / 33 ms line)
  • 160.2.14 Annotation / bookmark on trace
  • 160.2.15 Export sub-range for sharing

160.3 @neith/profiler-gpu — GPU Frame Debugger#

  • 160.3.1 Capture single frame with all API calls
  • 160.3.2 Vulkan / Metal / DX12 / WebGPU capture
  • 160.3.3 Per-drawcall timing + shader time
  • 160.3.4 Texture viewer (mip / slice / face)
  • 160.3.5 Buffer viewer (hex + structured)
  • 160.3.6 Render state diff across draws
  • 160.3.7 Pipeline state breakdown
  • 160.3.8 Event hierarchy (RenderPass / SubPass / Cmd)
  • 160.3.9 Pixel history (what wrote this fragment)
  • 160.3.10 Mesh preview (pre / post VS)
  • 160.3.11 Shader source + IL + ISA display
  • 160.3.12 Shader-debug step-through (Nsight / PIX-style)
  • 160.3.13 Asset lookup in engine (click → source)
  • 160.3.14 Overdraw visualisation
  • 160.3.15 Quad-efficiency / wave-occupancy stats
  • 160.3.16 Memory barrier timeline
  • 160.3.17 Compute dispatch inspection
  • 160.3.18 Raytracing acceleration structure view
  • 160.3.19 HLSL / GLSL / MSL / WGSL SPIR-V cross-pipeline
  • 160.3.20 Remote capture (console / mobile)

160.4 @neith/profiler-memory — LLM / Low-Level Memory#

  • 160.4.1 Per-tag memory tracker
  • 160.4.2 Allocation timeline
  • 160.4.3 Heap fragmentation visualisation
  • 160.4.4 Leak detector with callstack
  • 160.4.5 Paged pool (GPU / CPU) usage curve
  • 160.4.6 Texture / mesh / shader memory slice
  • 160.4.7 Asset dependency graph
  • 160.4.8 Snapshot diff (between two frames)
  • 160.4.9 Virtual memory mapping view
  • 160.4.10 Out-of-memory early-warning
  • 160.4.11 Budget per subsystem
  • 160.4.12 Build-size bloom analyser
  • 160.4.13 Asset-cook report with deduplication stats
  • 160.4.14 Memory pressure simulation
  • 160.4.15 Integration with Phase 42 asset pipeline

160.5 @neith/profiler-net — Network Profiler#

  • 160.5.1 Per-connection bandwidth timeline
  • 160.5.2 Replication byte breakdown by actor + property
  • 160.5.3 RPC frequency + size per function
  • 160.5.4 Ping / jitter / loss time-series
  • 160.5.5 Packet capture view (headers + payload)
  • 160.5.6 Ack / re-send visualisation
  • 160.5.7 Congestion / pacing graph
  • 160.5.8 Prediction / rollback events
  • 160.5.9 Session replay with packet-step
  • 160.5.10 Cross-reference with Phase 159 OSS

160.6 @neith/profiler-stat — Stat Commands & In-Game HUD#

  • 160.6.1 stat unit frame-time overlay
  • 160.6.2 stat fps / stat gpu / stat scene
  • 160.6.3 Custom stat groups
  • 160.6.4 Overlay graph (30-frame history)
  • 160.6.5 Hitch detector ≥ threshold
  • 160.6.6 Colour-coded per-thread bar
  • 160.6.7 Key-binding toggle
  • 160.6.8 Console command interface
  • 160.6.9 Cheat-protected in shipping
  • 160.6.10 Screenshot-with-overlay capture

160.7 @neith/profiler-sample — Sample-based Profiler (Production)#

  • 160.7.1 Continuous low-overhead sampling
  • 160.7.2 ETW / perf / DTrace / signpost backends
  • 160.7.3 Symbolication (Phase 149 symbol server reuse)
  • 160.7.4 Aggregation across players (opt-in)
  • 160.7.5 Device-class cohort (GPU tier / CPU gen)
  • 160.7.6 Hotspot regression alert per build
  • 160.7.7 Statistical bootstrap + confidence intervals
  • 160.7.8 Long-session trend
  • 160.7.9 Per-level telemetry
  • 160.7.10 Server-side matchmaking-health profile

160.8 @neith/profiler-shader — Shader Profiler & Analyzer#

  • 160.8.1 Static analyser (estimated cost)
  • 160.8.2 GPU hardware counter sampling
  • 160.8.3 Wave / warp occupancy
  • 160.8.4 VGPR / SGPR usage
  • 160.8.5 Instruction mix (ALU / MEM / CTRL)
  • 160.8.6 Texture fetch latency
  • 160.8.7 Shader variant matrix cost summary
  • 160.8.8 Auto-suggest loop / branch optimisation
  • 160.8.9 Cross-compile with DXIL / SPIRV / MSL / AIR diff
  • 160.8.10 Shader permutation explosion detector

160.9 @neith/profiler-physics — Physics Profiler#

  • 160.9.1 Broad-phase vs narrow-phase timing
  • 160.9.2 Constraint solver iteration count
  • 160.9.3 Contact count timeline
  • 160.9.4 Sleeping / awake body ratio
  • 160.9.5 Collision pair hot-list
  • 160.9.6 Fluid / cloth / hair (Phase 155 / 157) sim timings
  • 160.9.7 Substep adaptation events
  • 160.9.8 Island-graph visualisation
  • 160.9.9 Determinism check counter
  • 160.9.10 Anomaly alert (stuck body / excessive energy)

160.10 @neith/profiler-audio — Audio Profiler#

  • 160.10.1 Voice count / slot usage
  • 160.10.2 DSP budget per bus
  • 160.10.3 Plugin-host CPU (Phase 132) integration
  • 160.10.4 Buffer-underrun events
  • 160.10.5 Mix-graph cost flamegraph
  • 160.10.6 HRTF / convolution cost
  • 160.10.7 Asset-load hitches
  • 160.10.8 Dialogue / music / SFX stem usage
  • 160.10.9 Latency between trigger and sound
  • 160.10.10 Correlate audio stutter with CPU / GPU

160.11 @neith/profiler-asset — Asset & Cook Profiler#

  • 160.11.1 Cook-time per asset
  • 160.11.2 Build-graph bottleneck
  • 160.11.3 Asset-dependency graph
  • 160.11.4 Hot-reload frame cost
  • 160.11.5 Shader compile time
  • 160.11.6 Texture streaming load events
  • 160.11.7 Virtual texture page requests
  • 160.11.8 Disk IO hotspots
  • 160.11.9 Cross-reference with Phase 145 CI cache
  • 160.11.10 Build-size delta per commit

160.12 @neith/profiler-ui — Profiler UI & Workflow#

  • 160.12.1 Desktop app (standalone) + embedded panel
  • 160.12.2 Web viewer (HTML/WebGPU)
  • 160.12.3 Remote trace via TCP / WebSocket
  • 160.12.4 Two-way sync (click in trace → jump to editor)
  • 160.12.5 Multi-trace compare (A / B)
  • 160.12.6 Saved queries
  • 160.12.7 Collaborative annotation
  • 160.12.8 Export PNG / SVG / JSON
  • 160.12.9 Colour-blind friendly palette
  • 160.12.10 Dark / light / high-contrast themes

160.13 @neith/profiler-crash — Post-Mortem & Aftermath#

  • 160.13.1 GPU crash mini-dump (Nsight Aftermath-style)
  • 160.13.2 Last-submitted command buffer capture
  • 160.13.3 Driver timeout detection
  • 160.13.4 Shader-TDR summary
  • 160.13.5 Cross-reference Phase 149 crash ingest
  • 160.13.6 Heap corruption guard-page detection
  • 160.13.7 Stack overflow detection
  • 160.13.8 Deadlock / lock-inversion detector
  • 160.13.9 Health watchdog auto-snapshot
  • 160.13.10 Post-mortem report bundle

160.14 Testing & Validation#

@neith/profiler-testing is the cross-crate validation suite. The report::coverage matrix records the honest status of every gate; the three gates fully satisfiable in-process are checked below. The remaining seven need a real GPU + RenderDoc, a live LAN/WAN or MMO server, physical devkits, the engine fleet, or a multi-hour wall-clock soak — each has an in-process evidence harness (loopback stream, bounded soak, synthetic open-world / MMO load) but the literal external gate cannot be exercised on a headless CI box, so they stay unchecked.

  • 160.14.1 Overhead ≤ 3 % with default instrumentation
  • 160.14.2 Trace-file open latency < 2 s for 1 GB
  • 160.14.3 GPU capture fidelity vs RenderDoc reference — needs RenderDoc + a real GPU (our capture round-trip fidelity is validated by fidelity::gpu_capture_roundtrip)
  • 160.14.4 Shader-stepping accuracy regression
  • 160.14.5 Remote capture over LAN / WAN — needs two hosts + live sockets (framing/reassembly validated over loopback by stream_test::loopback_roundtrip)
  • 160.14.6 Sample-profiler stability (no crash) 24 h — a literal 24 h soak is a wall-clock run (bounded stability validated by soak::sample_soak)
  • 160.14.7 Dogfood: Phase 42 engine fleet always-on tracing — needs the running engine fleet
  • 160.14.8 Phase 79 open-world 6 h recorded trace analysable — needs a 6 h shipping-game recording (large synthetic trace analysed by dogfood::analyze_open_world)
  • 160.14.9 Phase 77 MMO server trace load test — needs a live load-tested MMO server (synthetic server load validated by dogfood::mmo_server_load)
  • 160.14.10 Console / mobile remote capture support — needs physical devkits + their SDKs