liamg / grace

:screwdriver: It's strace, with colours.

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.

grace's Issues

what's news

hello, thanks for your this interesting pkg

on AUR grace is flagged out-of-date since 2024-02-08 & on this repo
the last commit is out than 2 year.
so my question: do Grace is complete or do you have to implement some other features?

thanks

nice job! Do you have more detailed instructions？

Anotha One

The rate at which you release projects along with quality and effectiveness of said projects is beginning to cause many of the rest of us to look bad. Every day I wake up and am invaded with intrusive thoughts to the tune of:

"when will you catch up to liamg?"

"he's not just making IRC bots anymore, why are you still committing to your silly little girc fork?"

"maybe if you were good at anything you would spend as much time as liamg does with the syscall and unsafe libraries but here you are still learning how to use sync.Pool properly"

I presume one should be able to reproduce this bug on many platforms. I beg of you on behalf of the entire golang community to slow down and maybe just release a dud or two so we don't all look as bad.

Thanks One Million!

---

P.S: I don't know what Discussions is but this is an issue.

Ctrace as an inspiration

Hi Liam.

Great tool. Maybe you could drawn some additional inspiration from: https://github.com/automation-stack/ctrace. Statistics is one of a greatest features there.

"Strace for dummies" that's a great idea. Would be awesome to have dummy levels, basically verbosity.

And filtering by syscall category, would be awesome too. Like --filter file/--filter capabilities

I know it's a lot of work. And I couldn't help you, because I'm not good with go. But I'll definitely make AUR package (archlinux) for grace, maybe it will help somehow.