Fighting Game · Guides & deep dives

V2 Tracy Profiling Workflow

The Tracy integration is contract validated by these gates:

7sections3 minread
Markdown source
On this page

This guide is the operator-facing workflow for the Phase 72 Tracy integration. The implementation contracts live under V2/ue/Build/Performance and the Rust instrumentation lives in libs/maya/engine-core.

Source Of Truth#

The Tracy integration is contract validated by these gates:

  • v2-tracy-client-dependencies.json verifies the workspace tracy-client dependency and optional tracy feature shape.
  • v2-tracy-zone-macros.json verifies CPU zone macros and hot-path coverage.
  • v2-tracy-frame-mark.json verifies main-loop frame boundaries.
  • v2-tracy-gpu-zone-integration.json verifies GPU pass and timestamp spans.
  • v2-tracy-memory-tracking.json verifies allocator lifetime tracking.
  • v2-tracy-lock-tracking.json verifies mutex and rwlock contention tracking.
  • v2-tracy-message-logging.json verifies timeline log messages.
  • v2-tracy-plot-tracking.json verifies frame metric plots.
  • v2-tracy-fiber-tracking.json verifies fiber enter and leave scopes.
  • v2-tracy-network-profiling.json verifies packet rate, bandwidth, and RTT plots in maya-nexus.
  • v2-tracy-shipping-strip.json verifies zero-overhead shipping builds.
  • v2-tracy-capture-automation.json verifies local capture automation.
  • v2-tracy-ci-integration.json verifies automated capture and p95 regression gating.
  • v2-tracy-zone-colors.json verifies renderer blue, physics green, and AI red zone colors.

Run all Tracy contract checks from the repository root with:

bash
for script in V2/ue/Tools/check-v2-tracy-*.py; do python3 "$script"; done
python3 V2/ue/Tools/run-v2-tracy-ci-capture.py --self-test

Local Profiling#

Build and test with the tracy feature only when collecting diagnostics:

bash
cd libs/maya/engine-core
CARGO_BUILD_JOBS=1 cargo check -p maya-renderer --features tracy
CARGO_BUILD_JOBS=1 cargo check -p maya-physics --features tracy
CARGO_BUILD_JOBS=1 cargo check -p maya-souls --features tracy
TRACY_NO_INVARIANT_CHECK=1 CARGO_BUILD_JOBS=1 cargo test -p maya-souls --lib --features tracy

Use TRACY_NO_INVARIANT_CHECK=1 only on hosts where Tracy aborts with the invariant TSC warning. Leave it unset on profiling machines with invariant TSC support.

Start the game or targeted test process with the relevant Rust crate compiled with --features tracy, then connect Tracy UI or run the capture tool. The default manual capture path is Saved/Profiling/Tracy/maya-capture.tracy.

Capture Workflow#

Manual capture uses tracy-capture with the same flags enforced by CI:

bash
tracy-capture -o Saved/Profiling/Tracy/maya-capture.tracy -a 127.0.0.1 -p 8086 -f -s 10 -m 4096

The engine automation path is TracyCaptureAutomation in maya-profiler. It supports Manual, Frame, and Named triggers, creates output directories before spawning the capture tool, and records status as Armed, Capturing, Saved, or Failed.

Capture artifacts used by CI are written to V2/ue/Saved/Profiling/TracyCI/v2-ci-capture.tracy; the matching JSON report is V2/ue/Saved/Profiling/TracyCI/v2-tracy-ci-report.json.

CI Regression Gate#

CI runs:

bash
python3 V2/ue/Tools/run-v2-tracy-ci-capture.py --self-test
python3 V2/ue/Tools/check-v2-tracy-ci-integration.py
python3 V2/ue/Tools/check-v2-tracy-profiling-workflow.py

run-v2-tracy-ci-capture.py wraps the test command, starts tracy-capture, requires the capture artifact when --required-artifact is present, and writes a v2.performance.tracyCiReport.v1 report. The regression gate reads baseline and current frame exports from V2/ue/Saved/Profiling/TracyCI/baseline and V2/ue/Saved/Profiling/TracyCI/current. It fails when current p95FrameTimeMs is more than 10 percent above baseline p95.

Timeline Triage#

Use the color convention first:

  • Renderer zones are blue through MAYA_RENDERER_TRACY_ZONE_COLOR.
  • Physics zones are green through MAYA_PHYSICS_TRACY_ZONE_COLOR.
  • AI zones are red through MAYA_SOULS_TRACY_AI_ZONE_COLOR.

Then inspect the supporting tracks. The required triage signals are frame marks, GPU spans, memory callstacks, lock contention, timeline messages, plots, fiber scopes, and network plots.

  • Frame marks from maya_kernel_tracy_frame_mark! define frame boundaries.
  • GPU spans separate CPU submission from GPU timestamp upload.
  • Memory callstacks separate arena, pool, slab, and stack allocator lifetimes.
  • Lockable contexts reveal mutex and rwlock contention.
  • Tracy messages mirror engine log severity in the timeline.
  • Plots track entity count, draw calls, triangle count, physics bodies, and audio voices.
  • Fiber scopes identify coroutine scheduling gaps.
  • Network plots track packet rate, bandwidth, and RTT.

When a regression appears, preserve the .tracy artifact, the JSON report, the Git SHA, the test command, and the baseline/current p95 numbers in the incident or review note.

Shipping Policy#

Shipping builds must not enable Tracy. Every Tracy-capable crate keeps default = [], declares shipping, and rejects shipping+tracy with the compile-time guard:

text
Maya shipping builds must not enable the tracy feature; Tracy instrumentation is stripped by leaving tracy disabled.

Use cargo check -p <crate> --features shipping for shipping validation. An intentional cargo check -p <crate> --features 'shipping tracy' must fail with that guard message.

Verification#

Before accepting Tracy workflow changes, run the focused checks:

bash
python3 V2/ue/Tools/check-v2-tracy-profiling-workflow.py
python3 V2/ue/Tools/check-v2-tracy-zone-colors.py
python3 V2/ue/Tools/check-v2-tracy-shipping-strip.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Build/Performance/v2-tracy-profiling-workflow.json

For code changes that touch profiling macros or feature flags, also run the affected crate checks and tests with --features tracy.