Split oversized traces into PIPE_BUF-sized chunks instead of dropping them

[rlerdorf]

Supersedes #157, following the design from our Slack thread: rather than truncating a trace that doesn't fit in -b, assemble the whole trace and emit it as chunks of at most -b bytes, each tagged with a # trace_id = <id>.<k>/<n> record, and glue them back together in stackcollapse-phpspy.pl. Users don't need to think about buffer sizes, -J m, or per-pid files anymore.

The bug

A trace larger than -b is dropped in full: the BUF_FULL from the handler aborts the walk in do_trace(), and STACK_END (hence the write) never runs. Deep stacks are lost preferentially, and the log line says "truncating" while doing the opposite. Measured with a 200-frame recursion at the default -b: 0 traces written on master vs 198 with -b 65536. After this change, 198 at the default.

How it works now

• event_fout.c assembles the trace in a growable per-handler buffer (realloc, offset-based, hard cap 4 MiB — PHPSPY_MAX_STACK_WALK × the max frame line is ~800 KB, so this is generous). The -f/-F filter runs over the whole assembled trace at STACK_END (previously it only ever saw the first -b bytes — a small behaviour change worth knowing about).
• The buffer is split at record boundaries into chunks of ≤ -b bytes. Every record ends with the frame delimiter and repl_delim already guarantees no record contains one, so scanning back from the cap is a safe boundary search. Each chunk is written with one writev(2) (payload + marker), which is atomic on a pipe for ≤ PIPE_BUF bytes — same guarantee the single write() relied on.
• -b now means "max bytes per write" and defaults to PIPE_BUF (<limits.h>), min 128. Values above PIPE_BUF are still allowed with the existing warning (useful with -o file.%d), and the help text no longer refers to a -J m flag that doesn't exist.
• The trace id is a process-global atomic counter (same pattern as trace_count), so concurrent -P workers never collide. --event-handler-opts m now holds the mutex across all of a trace's chunks, so with it a trace is contiguous in the stream.
• stackcollapse-phpspy.pl groups frames by id and emits a stack when chunk n-1 arrives; incomplete or out-of-order ids are discarded with a warning rather than emitted as partial stacks. Pre-trace_id capture files still work (legacy depth-0 path). Reader state is bounded: each writer thread has at most one trace in flight. top.c needs no changes — it already skips # lines and tallies per line.

The cases chunking can't fix — a single record longer than a chunk's payload, -1/--single-line mode (the marker joins with \t, so a trace stays one line; chunking is disabled there), or the 4 MiB cap — emit # truncated = 1, drop the rest of that trace (no holes), and STACK_END returns PHPSPY_ERR_BUF_FULL after writing, so the sample still counts toward --limit via PHPSPY_TRACE_COUNTED().

Independent fixes carried over from #157

• The trace delimiter is now unconditional. On master, when the -d epilogue didn't fit, the delimiter was lost and consecutive traces merged. Measured: -d pt -b 1063 → 198 traces / 0 blank lines on master, 198/198 after. (While here: try_break in phpspy.h is broken — its break binds to the macro's own do/while(0) — and this PR removes its only user. Left the macro alone as out of scope.)
• A failed vsnprintf re-terminates the buffer so a partial record is never visible to the filter or the write.
• Truncation is logged once per handler, not once per frame at 99 Hz.

Tests

• test_buffer_full.sh (rewritten): deep stack at -b 128 keeps every frame, has a continuation marker, no truncation; the filter still applies to the whole trace.
• test_truncate.sh (new): oversized single record → # truncated = 1, one delimiter per trace, --limit still terminates; -1 mode stays one line per trace.
• test_chunk_interleave.sh (new): two children with disjoint function names traced with -P --threads 2 -b 512, collapsed output must contain both and no stack may mix them; plus a round-trip asserting no sample lost and no stack cut short. 12/12 runs clean.
• test_stackcollapse.sh (new): hand-interleaved chunk fixtures, legacy input, out-of-order chunk.
• Full suite: 20/20 on php8.4 and 8.6; the only failures on other versions are ones already failing on master (pdo_args_packed_array on 7.2–8.2, the 7.0 frame-slot varpeek cases fixed in Fix PHP 8.6 sapi_globals offset, PHP 7.0 frame-slot bug, and get real aarch64 struct data #165). make shellcheck clean; the USE_ZEND=1 build adds no new errors in event_fout.c.

Manual check: two 60-deep children under -P -T2 -b 512 → 572 traces in 2860 chunks (up to 5 per trace), 0 mixed stacks, all 572 samples recovered by the Perl script.

No PHPSPY_VERSION bump.

🤖 Generated with Claude Code