Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/1pkg/gotcha
Gotcha 🎯 seamlessly patches go runtime to provide a convenient way to track amount of heap allocated bytes, objects, calls per goroutine.
https://github.com/1pkg/gotcha
allocation context go golang memory memory-allocation
Last synced: about 10 hours ago
JSON representation
Gotcha 🎯 seamlessly patches go runtime to provide a convenient way to track amount of heap allocated bytes, objects, calls per goroutine.
- Host: GitHub
- URL: https://github.com/1pkg/gotcha
- Owner: 1pkg
- License: mit
- Created: 2020-11-25T12:54:00.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-10-21T07:07:31.000Z (about 2 years ago)
- Last Synced: 2024-06-20T07:55:41.841Z (5 months ago)
- Topics: allocation, context, go, golang, memory, memory-allocation
- Language: Go
- Homepage:
- Size: 4.18 MB
- Stars: 39
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# Gotcha 🎯
[](https://github.com/1pkg/gotcha/actions?query=workflow%3Alint+branch%3Amaster+)
[](https://github.com/1pkg/gotcha/actions?query=workflow%3Atest+branch%3Amaster+)
[](https://goreportcard.com/report/github.com/1pkg/gotcha?nocache=1)
[](https://github.com/1pkg/gotcha/blob/master/go.mod)
[](LICENSE)
[](https://pkg.go.dev/github.com/1pkg/gotcha?tab=doc)
`go get -u github.com/1pkg/gotcha`
[blog post article](https://1pkg.github.io/posts/lets_trace_goroutine_allocated_memory/)
## Introduction
Gotcha seamlessly patches go runtime to provide a convenient way to track amount of heap allocated bytes, objects, calls per goroutine.
```go
package main
import (
"context"
"fmt"
"github.com/1pkg/gotcha"
)
func main() {
var v []int
gotcha.Trace(context.Background(), func(ctx gotcha.Context) {
v = make([]int, 100)
b, o, c := ctx.Used() // bytes objects calls
fmt.Println("initial allocation", b, o, c) // will print "initial allocation 824 101 2"
gotcha.Trace(ctx, func(ctx gotcha.Context) {
v = make([]int, 5000)
b, o, c := ctx.Used() // bytes objects calls
fmt.Println("derived allocation", b, o, c) // will print "derived allocation 40024 5001 2"
})
select {
case <-ctx.Done():
b, o, c := ctx.Used() // bytes objects calls
fmt.Println("total allocations", b, o, c) // will print "total allocations 41840 5116 15"
default:
panic("unreachable")
}
}, gotcha.ContextWithLimitBytes(gotcha.KiB)) // set context allocation limit to one kilobit
// note that prints above might be slightly different on your machine
fmt.Println(len(v)) // 5000
}
```
## Internals
Gotcha exposes function `Track` that tracks memory allocations for provided `Tracer` function. All traced allocations are attached to the single parameter of this tracer function `Context` object. Gotcha context fully implements `context.Context` interface and could be used to cancel execution if provided limits were exceeded. Gotcha supports nested tracing by providing gotcha context as the parent context for derived `Tracer`; then gotcha tracing context methods will also be targeting parent context as well as derived context.
Note that in order to work gotcha uses [1pkg/gomonkey](https://github.com/1pkg/gomonkey) based on [bou.ke/monkey](https://github.com/bouk/monkey) and [1pkg/golocal](https://github.com/1pkg/golocal) based on [modern-go/gls](https://github.com/modern-go/gls) packages to patch runtime `mallocgc` allocator entrypoint and trace per goroutine context limts. This makes gotcha inherits the same list of restrictions as `modern-go/gls` and `bou.ke/monkey` [has](https://github.com/bouk/monkey#notes).
It's important to know that gotcha is not trying to measure momentary memory usage which involves GC tracing into the act, keeping track on GC is rather a big task on it's own and out of scope for gotcha. Instead gotcha traces all memory allocated in monotonic increasing fashion where is only allocations are taken into consideration and all deallocations are discarded.
Note: despite that `gotcha` might work on your machine, it's super unsafe. It uses code assumption about `mallocgc`, depends on calling convention that could be changed, uses platform specific machine code direcly, etc. Alsp `gotcha` isn't expected to work on anything apart from `amd64` with latest go runtime. So I highly discourage anyone to use gotcha in any production code or maybe even any code at all as it's extremely unsafe and not reliable and won't be supported in foreseeable future. Nevertheless, one could probably imagine reasonable use cases for this concept library in go benchmarks or test. Finally it's worth to say that primary intention to develop gotcha was learning and that gotcha doesn't have comprehensive tests coverage and support and not ready for any serious use case anyway
## Licence
Gotcha is licensed under the MIT License.
See [LICENSE](LICENSE) for the full license text.