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+). Then make build is your friend.