Skip to content

Latest commit

 

History

History
124 lines (82 loc) · 4.43 KB

README.md

File metadata and controls

124 lines (82 loc) · 4.43 KB
Raw

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.