[rlerdorf]

A trace larger than -b is discarded in full, while the log line says truncating.

The buffer is per-trace — reset at STACK_BEGIN, written once at STACK_END — so an overflow during a frame returns out of the handler via try, STACK_END never runs, and event_handler_fout_write is never called.

Why it matters

Deep stacks are dropped preferentially, so the profile is biased against exactly the recursive code you opened the profiler to look at. A 60-frame recursion, measured before the change:

-b	traces written	dropped
4096 (default)	3	143
65536	145	0

98% of samples lost at the default buffer size, and the only hint is a log line whose wording implies partial data was kept. After the change both sizes yield 146 traces, and every sample survives a stackcollapse-phpspy.pl round-trip.

-l was affected too: trace_count was gated on rv == PHPSPY_OK, so on such a target the limit could never be reached and --limit=N ran until the process died.

Approach

The handler absorbs the overflow — emits the frames that fit, appends # truncated = 1, and reports the truncation upward so the sample is still tallied and still counts toward -l.

Details that took some care, and are probably where review is best spent:

• The epilogue reserve comes out of the existing budget, not on top of it. Growing the buffer past PIPE_BUF would reintroduce interlaced writes in -P mode — the hazard the -b help text already warns about. Buffers under 128 bytes keep the old all-or-nothing behaviour.
• Once a trace truncates, later records are dropped too. Otherwise a short frame fits after a long one was refused, and the stack comes out with a silent hole in it rather than a clean tail.
• vsnprintf has already written its truncated copy by the time it reports failure, so the buffer is re-terminated at the cursor — otherwise -f matches against a partial frame that is never written.
• The trace delimiter is now guaranteed, overwriting the last byte if that is the only way to fit it. This is a pre-existing bug independent of the above: when the -d epilogue overflowed, try_break skipped the delimiter and two traces merged into one in the stream.
• One log line per handler instead of per frame. At 99 Hz on a deep stack the old one fires for every frame of every sample.

Compatibility

# truncated = 1 is a # comment line, so stackcollapse-phpspy.pl and top.c's parser both already skip it, exactly as they do for # uri = ….

One behaviour change worth calling out explicitly: tests/test_buffer_full.sh currently asserts that an over-budget trace produces nothing at all (not_expected[anything]='^.+$'). That is the behaviour this PR changes, so its second case is rewritten. If you would rather keep the drop as the default and put truncation behind a flag, say so and I will rework it — but I think a silently discarded sample is the wrong default for a sampling profiler.

Testing

make test passes (15/15) under both make and USE_ZEND=1 make against php8.3 and php8.4. tests/test_truncate.sh covers the marker, the delimiter invariant, and that no samples are lost in the round-trip.

Independent of #156 — they touch different code and can merge in either order.

[rlerdorf]

Replaced by #167