stackparse

README

gostackparse

Package stackparse parses goroutines stack trace dumps as produced by panic() or runtime.Stack().

Design Goals

1. Safe: No panics should be thrown.
2. Simple: Keep this pkg small and easy to modify.
3. Forgiving: Favor producing partial results over no results, even if the input data is different than expected.
4. Efficient: Parse several hundred MB/s.

Testing

gostackparse has been tested using a combination of hand picked test-fixtures, property based testing, and fuzzing.

Benchmarks

gostackparse includes a small benchmark that shows that it can parse test-fixtures/waitsince.txt at ~300 MB/s.

goos: darwin
goarch: amd64
pkg: github.com/DataDog/gostackparse
cpu: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
BenchmarkParse-12    	  44792	    26681 ns/op	297.74 MB/s	  17214 B/op	    306 allocs/op
PASS
ok  	github.com/DataDog/gostackparse	2.217s

License

This work is dual-licensed under Apache 2.0 or BSD3. See LICENSE.

Documentation

Overview

Package stackparse parses goroutines stack trace dumps as produced by panic() or runtime.Stack(). The design goals are:

1. Safe: No panics should be thrown. 2. Simple: Keep this pkg small and easy to modify. 3. Forgiving: Favor producing partial results over no results, even if the input data is different than expected. 4. Efficient: Parse several hundred MB/s.

Index

• func Fuzz(data []byte) int
• type Frame
• type Goroutine
  • func Parse(r io.Reader) ([]*Goroutine, []error)

Functions

func Fuzz

func Fuzz(data []byte) int

Fuzz implements fuzzing using https://github.com/dvyukov/go-fuzz. See TestFuzzCorupus for generating an initial test corpus.

Types

type Frame

type Frame struct {
	// Func is the name of the function, including package name, e.g. "main.main"
	// or "net/http.(*Server).Serve".
	Func string
	// File is the absolute path of source file e.g.
	// "/go/src/example.org/example/main.go".
	File string
	// Line is the line number of inside of the source file that was active when
	// the sample was taken.
	Line int
}

Frame is a single call frame on the stack.

type Goroutine

type Goroutine struct {
	// ID is the goroutine id (aka `goid`).
	ID int
	// State is the `atomicstatus` of the goroutine, or if "waiting" the
	// `waitreason`.
	State string
	// Wait is the approximate duration a goroutine has been waiting or in a
	// syscall as determined by the first gc after the wait started. Aka
	// `waitsince`.
	Wait time.Duration
	// LockedToThread is true if the goroutine is locked by a thread, aka
	// `lockedm`.
	LockedToThread bool
	// Stack is the stack trace of the goroutine.
	Stack []*Frame
	// FramesElided is true if the stack trace contains a message indicating that
	// additional frames were elided. This happens when the stack depth exceeds
	// 100.
	FramesElided bool
	// CreatedBy is the frame that created this goroutine, nil for main().
	CreatedBy *Frame
}

Goroutine represents a single goroutine and its stack after extracting it from the runtime.Stack() text format. See [1] for more info. [1] https://github.com/felixge/go-profiler-notes/blob/main/goroutine.md

func Parse

func Parse(r io.Reader) ([]*Goroutine, []error)

Parse parses a goroutines stack trace dump as produced by runtime.Stack(). The parser is forgiving and will continue parsing even when encountering unexpected data. When this happens it will try to discard the entire goroutine that encountered the problem and continue with the next one. It will also return an error for every goroutine that couldn't be parsed. If all goroutines were parsed successfully, the []error slice is empty.