Trace viewer

The /trace page opens finalized .qs-trace.ndjson.gz dumps and renders them as an aligned timeline. It does not require a running Minecraft server. The file is decompressed and parsed locally in a browser worker; the viewer does not upload it or make a network request for the local source.

Open a dump

1. Finish the capture with /qs trace stop and wait for the final path.
2. Open the Trace viewer.
3. Choose the file below <gameDir>/questscript-traces/ or drop it onto the page.

The viewer validates GZIP, NDJSON, and the schema version before rendering. Incompatible, empty, or truncated input is shown as an explicit error and never reaches the timeline.

Read the timeline

• Server ticks shows real tick boundaries, game logic, Script-attributable main-thread time, and overrun against the 50 ms budget.
• Server Script, ScriptRunner, and an optional Other lane use raw monotonic timestamps rather than invented worker ticks.
• Use the wheel to zoom. Use Shift with the wheel or drag to pan. Drag without Shift to select a range.
• Select a tick, span, or Host Object operation to inspect IDs, lane, observed ticks, outcome, and exact timestamps. Selecting an execution highlights correlated intervals across lanes.

The summary above the timeline reports total and median/p95/maximum Script main-thread time, share of tick time, and overruns. The table below preserves recorder-derived per-Script logical, active, wait, queue, and handoff metrics.

Metadata reports Recorder preparation separately. This one-time duration runs from the start of /qs trace start until the armed session is ready and covers checks, snapshots, spool opening, and initial JVM diagnostics. It completes before the first captured tick and is excluded from every tick duration and overrun.

Capture itself has an observer effect. Host Object operation records are written synchronously before the Host Object wrapper returns and may remain inside the enclosing guest span, so the displayed active, queue, tick, and overrun metrics are recorder-derived diagnostics rather than uninstrumented runtime timing. Start with /qs diagnostics threading for routine budget and queue inspection; enable tracing only when complete tick, execution, and operation records are required.

Result analyzer

After opening a dump, the viewer deterministically builds a result analysis in the same browser worker. For threading-workload/1.0.0-rc.3, versioned Script roles are classified as fan-out or writer, while language comes from the header Script snapshot. The table shows the four observed fan-out/writer by JavaScript/Python groups. Each group reports Script and execution counts, active/server-thread/wait/queue time, await and operation counts, active time, and operations per completed execution.

A second table groups every raw Host Object operation by operation_kind, access mode, and lane. It reports count, total and mean recorded duration, result bytes, outcomes, and boundary violations. Total duration is diagnostic: nested Host Object intervals can overlap, so their sum is not capture wall-clock time.

The Download analysis JSON action saves the machine-readable result locally. The JSON contains the analyzer version, input dump raw SHA-256, workload/prototype/host metadata, a separate recorderPreparationDurationNanos, stably sorted groups and operation kinds, totals, and mismatch warnings. The same dump produces the same JSON independently of locale, timeline zoom, or selection. Unknown workload roles are not guessed from display text; they remain in an explicit unclassified group.

Completeness

Use a capture for prototype comparison only when complete=true, the raw hash is verified, and there are no integrity errors, dropped events, open executions, or truncated tick. benchmarkValid is a separate workload-validation result; diagnostic dumps normally leave it null.

Public links and automatic upload are not part of this version. The viewer already separates the byte source from its parser, model, and renderer so a future HTTP source will not require another visualization format.