Documentation
¶
Overview ¶
Package stack analyzes stack dump of Go processes and simplifies it.
It is mostly useful on servers will large number of identical goroutines, making the crash dump harder to read than strictly necesary.
Example ¶
in := bytes.NewBufferString(crash)
goroutines, err := ParseDump(in, os.Stdout)
if err != nil {
return
}
// Optional: Check for GOTRACEBACK being set, in particular if there is only
// one goroutine returned.
// Use a color palette based on ANSI code.
p := &Palette{}
buckets := SortBuckets(Bucketize(goroutines, AnyValue))
srcLen, pkgLen := CalcLengths(buckets, false)
for _, bucket := range buckets {
io.WriteString(os.Stdout, p.BucketHeader(&bucket, false, len(buckets) > 1))
io.WriteString(os.Stdout, p.StackLines(&bucket.Signature, srcLen, pkgLen, false))
}
Output: panic: oh no! 1: running panic.go:464 panic(0, 0) main foo.go:45 crash2(0x7fe50b49d028, 0xc82000a1e0) main foo.go:50 main()
Index ¶
- func Augment(goroutines []Goroutine)
- func Bucketize(goroutines []Goroutine, similar Similarity) map[*Signature][]Goroutine
- func CalcLengths(buckets Buckets, fullPath bool) (int, int)
- type Arg
- type Args
- type Bucket
- type Buckets
- type Call
- func (c *Call) Equal(r *Call) bool
- func (c *Call) FullSourceLine() string
- func (c *Call) IsPkgMain() bool
- func (c *Call) IsStdlib() bool
- func (c *Call) Merge(r *Call) Call
- func (c *Call) PkgSource() string
- func (c *Call) Similar(r *Call, similar Similarity) bool
- func (c *Call) SourceLine() string
- func (c *Call) SourceName() string
- type Function
- type Goroutine
- type Palette
- type Signature
- type Similarity
- type Stack
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Augment ¶
func Augment(goroutines []Goroutine)
Augment processes source files to improve calls to be more descriptive.
It modifies goroutines in place.
Types ¶
type Arg ¶
type Arg struct {
Value uint64 // Value is the raw value as found in the stack trace
Name string // Name is a pseudo name given to the argument
}
Arg is an argument on a Call.
type Args ¶
type Args struct {
Values []Arg // Values is the arguments as shown on the stack trace. They are mangled via simplification.
Processed []string // Processed is the arguments generated from processing the source files. It can have a length lower than Values.
Elided bool // If set, it means there was a trailing ", ..."
}
Args is a series of function call arguments.
type Bucket ¶
Bucket is a stack trace signature and the list of goroutines that fits this signature.
type Buckets ¶
type Buckets []Bucket
Buckets is a list of Bucket sorted by repeation count.
func SortBuckets ¶
SortBuckets creates a list of Bucket from each goroutine stack trace count.
type Call ¶
type Call struct {
SourcePath string // Full path name of the source file
Line int // Line number
Func Function // Fully qualified function name (encoded).
Args Args // Call arguments
}
Call is an item in the stack trace.
func (*Call) FullSourceLine ¶
FullSourceLine returns "/path/to/source.go:line".
func (*Call) IsStdlib ¶
IsStdlib returns true if it is a Go standard library function. This includes the 'go test' generated main executable.
func (*Call) Similar ¶
func (c *Call) Similar(r *Call, similar Similarity) bool
Similar returns true if the two Call are equal or almost but not quite equal.
func (*Call) SourceLine ¶
SourceLine returns "source.go:line", including only the base file name.
func (*Call) SourceName ¶
SourceName returns the base file name of the source file.
type Function ¶
type Function struct {
Raw string
}
Function is a function call.
Go stack traces print a mangled function call, this wrapper unmangle the string before printing and adds other filtering methods.
func (Function) IsExported ¶
IsExported returns true if the function is exported.
func (Function) PkgDotName ¶
PkgDotName returns "<package>.<func>" format.
type Goroutine ¶
type Goroutine struct {
Signature // It's stack trace, internal bits, state, which call site created it, etc.
ID int // Goroutine ID.
First bool // First is the goroutine first printed, normally the one that crashed.
}
Goroutine represents the state of one goroutine, including the stack trace.
type Palette ¶
type Palette struct {
EOLReset string
// Routine header.
RoutineFirst string // The first routine printed.
Routine string // Following routines.
CreatedBy string
// Call line.
Package string
SourceFile string
FunctionStdLib string
FunctionStdLibExported string
FunctionMain string
FunctionOther string
FunctionOtherExported string
Arguments string
}
Palette defines the color used.
An empty object Palette{} can be used to disable coloring.
func (*Palette) BucketHeader ¶
BucketHeader prints the header of a goroutine signature.
type Signature ¶
type Signature struct {
// Use git grep 'gopark(|unlock)\(' to find them all plus everything listed
// in runtime/traceback.go. Valid values includes:
// - chan send, chan receive, select
// - finalizer wait, mark wait (idle),
// - Concurrent GC wait, GC sweep wait, force gc (idle)
// - IO wait, panicwait
// - semacquire, semarelease
// - sleep, timer goroutine (idle)
// - trace reader (blocked)
// Stuck cases:
// - chan send (nil chan), chan receive (nil chan), select (no cases)
// Runnable states:
// - idle, runnable, running, syscall, waiting, dead, enqueue, copystack,
// Scan states:
// - scan, scanrunnable, scanrunning, scansyscall, scanwaiting, scandead,
// scanenqueue
State string
CreatedBy Call // Which other goroutine which created this one.
SleepMin int // Wait time in minutes, if applicable.
SleepMax int // Wait time in minutes, if applicable.
Stack Stack
Locked bool // Locked to an OS thread.
}
Signature represents the signature of one or multiple goroutines.
It is effectively the stack trace plus the goroutine internal bits, like it's state, if it is thread locked, which call site created this goroutine, etc.
func (*Signature) Less ¶
Less compares two Signature, where the ones that are less are more important, so they come up front. A Signature with more private functions is 'less' so it is at the top. Inversely, a Signature with only public functions is 'more' so it is at the bottom.
type Similarity ¶
type Similarity int
Similarity is the level at which two call lines arguments must match to be considered similar enough to coalesce them.
const ( // ExactFlags requires same bits (e.g. Locked). ExactFlags Similarity = iota // ExactLines requests the exact same arguments on the call line. ExactLines // AnyPointer considers different pointers a similar call line. AnyPointer // AnyValue accepts any value as similar call line. AnyValue )
type Stack ¶
type Stack struct {
Calls []Call // Call stack. First is original function, last is leaf function.
Elided bool // Happens when there's >100 items in Stack, currently hardcoded in package runtime.
}
Stack is a call stack.
func (*Stack) Less ¶
Less compares two Stack, where the ones that are less are more important, so they come up front. A Stack with more private functions is 'less' so it is at the top. Inversely, a Stack with only public functions is 'more' so it is at the bottom.
Source Files