docs: document the strace textual format - #7226
Conversation
| an explanation of what to change: | ||
|
|
||
| ```sql | ||
| select name, value from stats where name like 'strace%' and value > 0 |
There was a problem hiding this comment.
use glob and nit add a semicolon
There was a problem hiding this comment.
Done: where name glob 'strace*' and value > 0;
| - You want to see *where* a process's wall-clock time goes inside the kernel: | ||
| which `read` blocked and for how long, how long a `futex` wait lasted, how | ||
| many `openat` calls a startup path makes — as a timeline rather than as | ||
| thousands of lines of text. |
There was a problem hiding this comment.
would be nice to have a e.g. query for this.
There was a problem hiding this comment.
Added one right under that bullet — top system calls by time spent inside them:
select name, count(*) as calls, sum(dur) as total_dur
from slice
where category = 'strace'
group by name
order by total_dur desc
limit 10;Checked it runs against a real strace capture.
| a pid there is no thread to attribute a system call to, so such lines are | ||
| dropped; see the `strace_missing_pid` stat. | ||
| - **Limitations:** | ||
| - Syscall arguments are kept as the single opaque string strace printed. |
There was a problem hiding this comment.
nit: pls use either system call or syscall
There was a problem hiding this comment.
Done — "system call" everywhere in prose now; --syscall-times stays as-is since that's the flag's actual name.
| `sh -c 'ls /usr/bin >/dev/null; sleep 0.1'` both ways, `-o` imports all 214 | ||
| system calls and drops none, while the stderr capture imports 140 and drops | ||
| 76. Tracing a program that never forks at all, the stderr capture imports |
There was a problem hiding this comment.
pls remove these numbers 214 and 76 as those vary system to system.
There was a problem hiding this comment.
Removed. Replaced with the part that doesn't depend on the machine: on a program that never forks, no second process is ever attached, so a stderr capture has no pid prefix on any line and imports nothing.
Perfetto has had an strace importer since the plugin landed, but the format is not mentioned anywhere in docs/ — a reader has no way to learn that an strace log can be opened at all, let alone which strace flags produce a log that imports cleanly. Add a section to the external-formats guide covering what the importer maps into (thread-track slices, category, args/ret, durations, blocked calls spanning their unfinished/resumed pair), the two flags that are mandatory (-ttt and -f) and why, the limitations, and how to capture a log in the first place. The example lines are verbatim from an strace 6.13 capture rather than hand-written, and the -o-versus-stderr advice is measured: tracing `sh -c 'ls /usr/bin >/dev/null; sleep 0.1'` both ways, -o imports all 214 syscalls and drops none while the stderr capture imports 140 and drops 76, because strace leaves the process it started unprefixed until a second one is attached.
47874bc to
7922437
Compare
2 participants
Depends on #7224 — please land that first. This describes the strace
importer's behaviour after that fix; on current
maina-Tcapture stillimports with zero-duration slices and the measured numbers below differ. Happy
to hold this until #7224 is in.
Perfetto has had an strace importer since the plugin landed, but the format is
not mentioned anywhere under
docs/. A reader has no way to find out that anstrace log can be opened at all, and — more painfully — no way to find out
which strace flags produce a log that imports cleanly. Get either of
-tttor-fwrong and the trace loads to an empty timeline, with the explanationburied in the
statstable.This adds a section to the external-formats guide covering:
stracecategory,args/ret,-Tdurations, and blocked calls spanning their<unfinished ...>/<... resumed>pair;-ttt,-f) and why each is required,each pointing at the stat that fires when it is missing;
fact that a
ptrace-based tool perturbs the timings it reports;Two things in it are measured rather than asserted:
hand-written — same method as the diff-test fixture in tp: fix the strace importer on real -f and -T output #7224.
-o FILE, don't redirect stderr" advice comes from tracingsh -c 'ls /usr/bin >/dev/null; sleep 0.1'both ways: with-o, all 214syscalls import and none are dropped; over stderr, 140 import and 76 are
dropped as
strace_missing_pid, because strace leaves the process itstarted unprefixed until a second one is attached. For a program that never
forks, the stderr capture imports nothing at all.
--syscall-timesis documented with the version it appeared in (strace 5.6,per the project's
NEWS) rather than left for the reader to discover bytrying it.
Verified:
tools/run_presubmitpasses on this branch.