Repository navigation
feat(xdebug-trace): streaming parser and summary for format-1 traces - #407
Merged
Merged
Conversation
Reads Xdebug function traces in the computer-readable format (xdebug.trace_format=1, "File format: 4"), plain or gzipped, line by line with bounded memory: entry, exit, return and assignment records, header and footer. Summarize makes one pass: call count, depth, duration, peak memory, top functions by self time, the slowest calls, and an index of byte offsets every 1000 calls for paging. Over the size limit, or without TRACE END, the trace is summarized up to where it stops and flagged truncated. Formats 0, 2, 3 and 4 are refused with a hint to set trace_format=1.
This was referenced Nov 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
First PR of Xdebug Trace v1 (GitHub #288): a parser only, no wiring yet. New package
modules/xdebugtrace:NewReader(r, limit)/Next()— streams a trace in the computer-readable format (xdebug.trace_format=1,File format: 4), plain or gzip (detected by magic bytes). Records: entry (level, fn#, time, memory, function, user/internal, include file, file, line, args), exit, return (collect_return), assignment (collect_assignments); header (Version,File format,TRACE START/END) and footer (end time, memory).Offset()gives the exact uncompressed byte offset of a record's line. Lines over 1 MB are cut (flagCut).Summarize(r, limit)— one pass, memory bounded by stack depth + top lists: calls, user calls, max depth, duration, peak memory, assignments,{main}script, top 20 functions by self time, 20 slowest calls (incl/self time, memory delta, offset), index point every 1000 calls (for the paged tree API in the next PR).TRACE END(fatal, killed worker) or with a broken gzip tail: summarized up to where it stops,truncated: true. Frames unwound by an exception close at their parent's exit.ErrNotFormat1(«set xdebug.trace_format=1»).Layout taken from Xdebug's
src/tracing/trace_computerized.c(header, entry/exit/return/assignment lines, footer).Tests
go vet+go test -race -count=1 ./modules/xdebugtrace/ok: records plain/gzip/CRLF, offsets point at entry lines, non-format-1 inputs, long line cut, summary numbers (self/incl time, memory delta, ordering), truncation (limit, no end, broken gzip), exception unwinding, 5000-call trace (top lists capped, index offsets exact).Checked on traces recorded by a live Xdebug 3.4.5 (PHP 8.3):
testdata/main.xt.gz({main}, require, methods, recursion, closure, exception, strings with tab/newline) andtestdata/mid.xt.gz(xdebug_start_trace()at depth 4, stopped byxdebug_stop_trace()); scripts and commands intestdata/README.md. Tests:TestRecorded_MainRecords,TestRecorded_MainSummary,TestRecorded_MidTrace.Made with harnsy