# V2 Tracy Profiling Workflow

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`.