strace: Trace System Calls of a Command
strace runs a program and logs each system call with its arguments and return value, exposing exactly which file, socket, or syscall failed.
When a CI command fails with a vague error or hangs with no output, strace shows the last syscall it made, often an ENOENT on a missing file or a blocking read on a socket.
What it does
strace intercepts and records the system calls a process makes and the signals it receives. Each line shows the call, its arguments, and the result; failures end in = -1 ENOENT (No such file or directory) and similar. -f follows forked children, essential for shells and test runners.
Common usage
strace -f -e trace=openat,connect ./run-tests
strace -f -o trace.log ./flaky-binary
# show only failing file opens
strace -f -e trace=open,openat ./app 2>&1 | grep ENOENT
strace -c ./app # syscall summary table on exitOptions
| Flag | What it does |
|---|---|
| -f | Follow child processes (fork/clone) |
| -e trace=<set> | Limit to syscalls, e.g. openat,connect,network,file |
| -o <file> | Write the trace to a file instead of stderr |
| -p <pid> | Attach to a running process |
| -c | Print a summary count of syscalls and time |
| -T | Show time spent in each syscall |
| -s <n> | Print up to n bytes of string arguments |
In CI
For a step that hangs, strace -f -p <pid> shows the syscall it is stuck in: read(3, blocking on a socket points at a network wait; futex( points at lock contention. For a "file not found" with no path, strace -f -e trace=openat ... | grep ENOENT reveals the exact missing path.
Common errors in CI
"strace: ptrace(PTRACE_TRACEME, ...): Operation not permitted" appears in containers without the SYS_PTRACE capability; run the container with --cap-add=SYS_PTRACE or --security-opt seccomp=unconfined. "strace: Process <pid> attached" then nothing usually means the process is genuinely idle. "strace: command not found" needs the strace package installed.