README
¶
grace
grace is a tool for monitoring and annotating syscalls for a given process.
It's essentially a lightweight strace, in Go, with colours and pretty output.
It's possible to tweak and filter the output to make it quite readable, for example (using -vnmx):
You can also review a summary of encountered syscalls (and sort by various columns):
grace vs. strace
grace isn't meant to compete with strace, it's purely meant to be a user-friendly, lightweight alternative. However, the following should provide a rough idea of what is supported in grace so far.
Over time grace is meant to become a simpler, more readable alternative to strace (strace for dummies?), albeit with reduced functionality/advanced features.
| Feature | grace | strace |
|---|---|---|
| Start a program and print all syscalls it makes | ✅ | ✅ |
Attach to an existing process by pid and print all syscalls it makes |
✅ | ✅ |
Filter syscalls by name, e.g. only show occurrences of the open syscall |
✅ | ✅ |
Filter syscalls using a given path, e.g. only show syscalls that access /etc/passwd |
✅ | ✅ |
| Dump I/O for certain file descriptors | ✅ | ✅ |
| Count occurrences and duration of all syscalls and present in a useful format | ✅ | ✅ |
| Print relative/absolute timestamps | ✅ | ✅ |
| Tamper with syscalls | ❌ | ✅ |
| Print extra information about file descriptors, such as path, socket addresses etc. | ✅ | ✅ |
| Print stack traces | ❌ | ✅ |
| Filter by return value | ✅ | ✅ |
| Pretty colours to make output easier to read | ✅ | ❌ |
| Lots of output options and customisation vectors | ✅ | ✅ |
| Output to file | ✅ | ✅ |
| Filter by failing/non-failing syscalls | ✅ | ✅ |
NOTE: Please feel free to add important strace features to this table, I'm working with a limited knowledge of strace.
Installation
Grab a statically compiled binary from the latest release.
Supported Platforms/Architecture
Currently only Linux/amd64 is supported. Other architectures coming soon.
If you'd like to implement a new architecture, you can duplicate tracer/sys_amd64.go and convert it to contain the syscall definitions for your arch.
Usage Examples
Trace a program
grace -- cat /dev/null # replace 'cat /dev/null' with your program
Trace an existing process
grace -p 123 # replace 123 with your pid
# e.g. you could use pgrep to find the pid of a process
grace -p `pgrep ping`
Trace a program and filter by syscall name
grace -f "name=openat" -- cat /dev/null
# you can also look for multiple syscalls
grace -f "name=openat&name=close" -- cat /dev/null
Trace a program and filter by syscall name and path
grace -f "name=openat&path=/dev/null" -- cat /dev/null
Trace a program and wire up stdin/out/err with the terminal
grace -F -- cat
Trace a program with maximum readability options
grace -vnmx -- cat /dev/null
Trace only failing syscalls
grace -Z -- cat /dev/null
Show a summary of syscalls with durations, counts and errors
grace -S -- cat /dev/null
Build Dependencies
If you want to build grace yourself instead of using the precompiled binaries, you'll need a recent version of Go (1.19+), musl-gcc installed (you can install musl-tools on Ubuntu or musl on Arch), and kernel headers (install linux-headers-$(uname -r) on Ubuntu or linux-headers and kernel-headers-musl on Arch). grace mainly just pulls constants from the kernel headers, so it's not a huge dependency. You should then have some success running make build. Note that many architectures are not yet supported (see below.)
Documentation
¶
There is no documentation for this package.
Source Files
Directories