Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/grantseltzer/weaver
Trace Go program execution with uprobes and eBPF
https://github.com/grantseltzer/weaver
bcc ebpf go golang linux trace tracing weaver
Last synced: 24 days ago
JSON representation
Trace Go program execution with uprobes and eBPF
- Host: GitHub
- URL: https://github.com/grantseltzer/weaver
- Owner: grantseltzer
- License: mpl-2.0
- Created: 2020-01-09T22:27:24.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-08-17T02:01:48.000Z (about 1 year ago)
- Last Synced: 2024-09-30T08:01:24.069Z (about 1 month ago)
- Topics: bcc, ebpf, go, golang, linux, trace, tracing, weaver
- Language: Go
- Homepage:
- Size: 7.84 MB
- Stars: 297
- Watchers: 13
- Forks: 19
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- go-awesome - Weaver - Tracking Go program execution links (Open source library / Debugging)
README
# Weaver
PLEASE READ! - I am currently refactoring Weaver to use libbpf instead of bcc which would include various other major improvements. If you're currently using weaver please be aware that features/bug fixes are being held off until the major refactor occurs. This will be tracked in the branch "refactor"
Weaver is a CLI tool that allows you to trace Go programs in order to inspect what values are passed to specified functions. It leverages eBPF attached to uprobes.
[](https://goreportcard.com/report/github.com/grantseltzer/weaver)
## Quick Start
There are two modes of operation, one that uses a 'functions file', and one that extracts a symbol table from a passed binary and filters by Go packages. More information on functionality in [docs](/docs).
### Functions file
Take the following example program:
test_prog.go
```go
package main
//go:noinline
func test_function(int, [2]int) {}
//go:noinline
func other_test_function(rune, int64) {}
func main() {
test_function(3, [2]int{1, 2})
other_test_function('a', 33)
}
```
Let's say we want to know what values are passed to `test_function` and `other_test_function` whenever the program is run. Once the program is compiled (`make`) we just have to create a file which specifies each function to trace:
functions_to_trace.txt
```
main.test_function(int, [2]int)
main.other_test_function(rune, int64)
```
Notice that we have to specify the parameter data types. (You can use `weaver --types` to see what data types are supported.)
Now we can call `weaver` like so:
```
sudo weaver -f /path/to/functions_to_trace.txt /path/to/test-prog-binary
```
Weaver will then sit idle without any output until `test-prog` is run and the `test_function` and `other_test_function` functions are called. This will also work on an already running Go Program.
```
{"functionName":"main.other_test_function","args":[{"type":"RUNE","value":"a"},{"type":"INT64","value":"33"}],"procInfo":{"pid":43300,"ppid":42754,"comm":"test-prog-binar"}}
{"functionName":"main.test_function","args":[{"type":"INT","value":"3"},{"type":"INT_ARRAY","value":"1, 2"}],"procInfo":{"pid":43300,"ppid":42754,"comm":"test-prog-binar"}}
```
### Package mode
For the same example Go program as above, you can choose to not specify a functions file. The command would like like this:
```
sudo weaver /path/to/test-prog-binary
```
This will default to only tracing functions in the `main` package, however you can use the `--packages` flag to specify a comma seperated list of packages (typially of the form `github.com/x/y`)
Output does include argument vlaues in this mode.
```
{"functionName":"main.main","procInfo":{"pid":44411,"ppid":42754,"comm":"test-prog-binar"}}
{"functionName":"main.test_function","procInfo":{"pid":44411,"ppid":42754,"comm":"test-prog-binar"}}
```
## Note on supported types
Currently weaver supports basic data types but getting support for user defined types is a high priority. Getting following types defined are a work in progress:
- user/stdlib defined structs
- user/stdlib defined interfaces
## System Dependencies
- [bcc](https://github.com/iovisor/bcc/blob/master/INSTALL.md) / bcc-devel
- linux kernel version > 4.14 (please make bug reports if your kernel version doesn't work)
## Build
`make` will compile the weaver binary to `bin/weaver` (It also creates the smoke test binary and print-stack utility)
Can't build? Please make an issue!
## Roadmap
Check issues for tasks currently being tracked. Please open bug reports, i'm sure there are plenty :-)
Short term goals include:
- Testing
- Output options
- Inspecting binaries for parameter data types instead of specifying them with a functions file
- CI/CD infrastructre
image modified version of art by Ashley McNamara ([license](https://creativecommons.org/licenses/by-nc-sa/4.0/)) based on art by Renee French.