README

Templates

Contains an HTML template and an icon.

emoji_u1f4a3.png is the bomb emoji U+1F4A3 in Noto Emoji as a PNG. emoji_u1f4a3_64.gif is the product of reducing the image to 64x64 and exporting as GIF.

Source

It can be found online at https://github.com/googlefonts/noto-emoji/blob/master/png/128/emoji_u1f4a3.png

License

Found in OFL.txt. An online copy can be retrieved at http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL

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 necessary.

    Example (HTML)

      Converts a stack trace from os.Stdin into HTML on os.Stdout, discarding everything else.

      Output:
      
      
      Example (Simple)

        A sample parseStack function expects a stdlib stacktrace from runtime.Stack or debug.Stack and returns the parsed stack object.

        Output:
        
        
        Example (Stream)

          Process multiple consecutive goroutine snapshots.

          Output:
          
          
          Example (Text)

            Runs a crashing program and converts it to a dense text format like pp does.

            Output:
            
            panic: 42
            
            1: running [Created by main.main @ main.go:7]
                main main.go:17 crashy.die(42)
                main main.go:8  main.func1()
            1: select (no cases)
                main main.go:10 main()
            exit status 2
            

            Index

            Examples

            Constants

            This section is empty.

            Variables

            This section is empty.

            Functions

            This section is empty.

            Types

            type Aggregated

            type Aggregated struct {
            	// Snapshot is a pointer to the structure that was used to generate these
            	// buckets.
            	*Snapshot
            
            	Buckets []*Bucket
            	// contains filtered or unexported fields
            }

              Aggregated is a list of Bucket sorted by repetition count.

              func (*Aggregated) ToHTML

              func (a *Aggregated) ToHTML(w io.Writer, footer template.HTML) error

                ToHTML formats the aggregated buckets as HTML to the writer.

                Use footer to add custom HTML at the bottom of the page.

                type Arg

                type Arg struct {
                	// Value is the raw value as found in the stack trace
                	Value uint64
                	// Name is a pseudo name given to the argument
                	Name string
                	// IsPtr is true if we guess it's a pointer. It's only a guess, it can be
                	// easily be confused by a bitmask.
                	IsPtr bool
                	// contains filtered or unexported fields
                }

                  Arg is an argument on a Call.

                  func (*Arg) String

                  func (a *Arg) String() string

                    String prints the argument as the name if present, otherwise as the value.

                    type Args

                    type Args struct {
                    	// Values is the arguments as shown on the stack trace. They are mangled via
                    	// simplification.
                    	Values []Arg
                    	// Processed is the arguments generated from processing the source files. It
                    	// can have a length lower than Values.
                    	Processed []string
                    	// Elided when set means there was a trailing ", ...".
                    	Elided bool
                    	// contains filtered or unexported fields
                    }

                      Args is a series of function call arguments.

                      func (*Args) String

                      func (a *Args) String() string

                      type Bucket

                      type Bucket struct {
                      	// Signature is the generalized signature for this bucket.
                      	Signature
                      	// IDs is the ID of each Goroutine with this Signature.
                      	IDs []int
                      	// First is true if this Bucket contains the first goroutine, e.g. the one
                      	// Signature that likely generated the panic() call, if any.
                      	First bool
                      	// contains filtered or unexported fields
                      }

                        Bucket is a stack trace signature and the list of goroutines that fits this signature.

                        type Call

                        type Call struct {
                        
                        	// Func is the fully qualified function name (encoded).
                        	Func Func
                        	// Args is the call arguments.
                        	Args Args
                        
                        	// RemoteSrcPath is the full path name of the source file as seen in the
                        	// trace.
                        	RemoteSrcPath string
                        	// Line is the line number.
                        	Line int
                        	// SrcName is the base file name of the source file.
                        	SrcName string
                        	// DirSrc is one directory plus the file name of the source file. It is a
                        	// subset of RemoteSrcPath.
                        	DirSrc string
                        
                        	// LocalSrcPath is the full path name of the source file as seen in the host,
                        	// if found.
                        	LocalSrcPath string
                        	// RelSrcPath is the relative path to GOROOT, GOPATH or LocalGoMods.
                        	RelSrcPath string
                        	// ImportPath is the fully qualified import path as found on disk (when
                        	// Opts.GuessPaths was set). Defaults to Func.ImportPath otherwise.
                        	//
                        	// In the case of package "main", it returns the underlying path to the main
                        	// package instead of "main" if Opts.GuessPaths was set.
                        	ImportPath string
                        	// Location is the source location, if determined.
                        	Location Location
                        	// contains filtered or unexported fields
                        }

                          Call is an item in the stack trace.

                          All paths in this struct are in POSIX format, using "/" as path separator.

                          type Func

                          type Func struct {
                          	// Complete is the complete reference. It can be ambiguous in case where a
                          	// path contains dots.
                          	Complete string
                          	// ImportPath is the directory name for this function reference, or "main" if
                          	// it was in package main. The package name may not match.
                          	ImportPath string
                          	// DirName is the directory name containing the package in which the function
                          	// is. Normally this matches the package name, but sometimes there's smartass
                          	// folks that use a different directory name than the package name.
                          	DirName string
                          	// Name is the function name or fully quality method name.
                          	Name string
                          	// IsExported is true if the function is exported.
                          	IsExported bool
                          	// IsPkgMain is true if it is in the main package.
                          	IsPkgMain bool
                          	// contains filtered or unexported fields
                          }

                            Func is a function call in a goroutine stack trace.

                            func (*Func) Init

                            func (f *Func) Init(raw string) error

                              Init parses the raw function call line from a goroutine stack trace.

                              Go stack traces print a mangled function call, this wrapper unmangle the string before printing and adds other filtering methods.

                              The main caveat is that for calls in package main, the package import URL is left out.

                              func (*Func) String

                              func (f *Func) String() string

                                String returns Complete.

                                type Goroutine

                                type Goroutine struct {
                                	// Signature is the stack trace, internal bits, state, which call site
                                	// created it, etc.
                                	Signature
                                	// ID is the goroutine id.
                                	ID int
                                	// First is the goroutine first printed, normally the one that crashed.
                                	First bool
                                
                                	// RaceWrite is true if a race condition was detected, and this goroutine was
                                	// race on a write operation, otherwise it was a read.
                                	RaceWrite bool
                                	// RaceAddr is set to the address when a data race condition was detected.
                                	// Otherwise it is 0.
                                	RaceAddr uint64
                                	// contains filtered or unexported fields
                                }

                                  Goroutine represents the state of one goroutine, including the stack trace.

                                  type Location

                                  type Location int

                                    Location is the source location, if determined.

                                    const (
                                    	// LocationUnknown is the default value when Opts.GuessPaths was false.
                                    	LocationUnknown Location = iota
                                    	// GoMod is a go module, it is outside $GOPATH and is inside a directory
                                    	// containing a go.mod file. This is considered a local copy.
                                    	GoMod
                                    	// GOPATH is in $GOPATH/src. This is either a dependency fetched via
                                    	// GO111MODULE=off or intentionally fetched this way. There is no guaranteed
                                    	// that the local copy is pristine.
                                    	GOPATH
                                    	// GoPkg is in $GOPATH/pkg/mod. This is a dependency fetched via go module.
                                    	// It is considered to be an unmodified external dependency.
                                    	GoPkg
                                    	// Stdlib is when it is a Go standard library function. This includes the 'go
                                    	// test' generated main executable.
                                    	Stdlib
                                    )

                                    func (Location) String

                                    func (i Location) String() string

                                    type Opts

                                    type Opts struct {
                                    	// LocalGOROOT is GOROOT with "/" as path separator. No trailing "/". Can be
                                    	// unset.
                                    	LocalGOROOT string
                                    	// LocalGOPATHs is GOPATH with "/" as path separator. No trailing "/". Can be
                                    	// unset.
                                    	LocalGOPATHs []string
                                    
                                    	// NameArguments tells panicparse to find the recurring pointer values and
                                    	// give them pseudo 'names'.
                                    	//
                                    	// Since the algorithm is O(n²), this can be worth disabling on live servers.
                                    	NameArguments bool
                                    
                                    	// GuessPaths tells panicparse to guess local RemoteGOROOT and GOPATH for
                                    	// what was found in the snapshot.
                                    	//
                                    	// Initializes in Snapshot the following members: RemoteGOROOT,
                                    	// RemoteGOPATHs, LocalGomoduleRoot and GomodImportPath.
                                    	//
                                    	// This is done by scanning the local disk, so be warned of performance
                                    	// impact.
                                    	GuessPaths bool
                                    
                                    	// AnalyzeSources tells panicparse to processes source files to improve calls
                                    	// to be more descriptive.
                                    	//
                                    	// Requires GuessPaths to be true.
                                    	AnalyzeSources bool
                                    	// contains filtered or unexported fields
                                    }

                                      Opts represents options to process the snapshot.

                                      func DefaultOpts

                                      func DefaultOpts() *Opts

                                        DefaultOpts returns default options to process the snapshot.

                                        type Signature

                                        type Signature struct {
                                        	// State is the goroutine state at the time of the snapshot.
                                        	//
                                        	// 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
                                        	//
                                        	// When running under the race detector, the values are 'running' or
                                        	// 'finished'.
                                        	State string
                                        	// CreatedBy is the call stack that created this goroutine, if applicable.
                                        	//
                                        	// Normally, the stack is a single Call.
                                        	//
                                        	// When the race detector is enabled, a full stack snapshot is available.
                                        	CreatedBy Stack
                                        	// SleepMin is the wait time in minutes, if applicable.
                                        	//
                                        	// Not set when running under the race detector.
                                        	SleepMin int
                                        	// SleepMax is the wait time in minutes, if applicable.
                                        	//
                                        	// Not set when running under the race detector.
                                        	SleepMax int
                                        	// Stack is the call stack.
                                        	Stack Stack
                                        	// Locked is set if the goroutine was locked to an OS thread.
                                        	//
                                        	// Not set when running under the race detector.
                                        	Locked bool
                                        	// contains filtered or unexported fields
                                        }

                                          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) SleepString

                                          func (s *Signature) SleepString() string

                                            SleepString returns a string "N-M minutes" if the goroutine(s) slept for a long time.

                                            Returns an empty string otherwise.

                                            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 Snapshot

                                              type Snapshot struct {
                                              	// Goroutines is the Goroutines found.
                                              	//
                                              	// They are in the order that they were printed.
                                              	Goroutines []*Goroutine
                                              
                                              	// LocalGOROOT is copied from Opts.
                                              	LocalGOROOT string
                                              	// LocalGOPATHs is copied from Opts.
                                              	LocalGOPATHs []string
                                              
                                              	// RemoteGOROOT is the GOROOT as detected in the traceback, not the on the
                                              	// host.
                                              	//
                                              	// It can be empty if no root was determined, for example the traceback
                                              	// contains only non-stdlib source references.
                                              	RemoteGOROOT string
                                              	// RemoteGOPATHs is the GOPATH as detected in the traceback, with the value
                                              	// being the corresponding path mapped to the host if found.
                                              	//
                                              	// It can be empty if only stdlib code is in the traceback or if no local
                                              	// sources were matched up. In the general case there is only one entry in
                                              	// the map.
                                              	RemoteGOPATHs map[string]string
                                              
                                              	// LocalGomods are the root directories containing go.mod or that directly
                                              	// contained source code as detected in the traceback, with the value being
                                              	// the corresponding import path found in the go.mod file.
                                              	//
                                              	// Uses "/" as path separator. No trailing "/".
                                              	//
                                              	// Because of the "replace" statement in go.mod, there can be multiple root
                                              	// directories. A file run by "go run" is also considered a go module to (a
                                              	// certain extent).
                                              	//
                                              	// It is initialized by findRoots().
                                              	//
                                              	// Unlike GOROOT and GOPATH, it only works with stack traces created in the
                                              	// local file system, hence "Local" prefix.
                                              	LocalGomods map[string]string
                                              	// contains filtered or unexported fields
                                              }

                                                Snapshot is a parsed runtime.Stack() or race detector dump.

                                                func ScanSnapshot

                                                func ScanSnapshot(in io.Reader, prefix io.Writer, opts *Opts) (*Snapshot, []byte, error)

                                                  ScanSnapshot scans the Reader for the output from runtime.Stack() in br.

                                                  Returns nil *Snapshot if no stack trace was detected.

                                                  If a Snapshot is returned, you can call the function again to find another trace, or do io.Copy(br, out) to flush the rest of the stream.

                                                  ParseSnapshot processes the output from runtime.Stack() or the race detector.

                                                  Returns a nil *Snapshot if no stack trace was detected and SearchSnapshot() was a false positive.

                                                  Returns io.EOF if all of reader was read.

                                                  The suffix of the stack trace is returned as []byte.

                                                  It pipes anything not detected as a panic stack trace from r into out. It assumes there is junk before the actual stack trace. The junk is streamed to out.

                                                  func (*Snapshot) Aggregate

                                                  func (s *Snapshot) Aggregate(similar Similarity) *Aggregated

                                                    Aggregate merges similar goroutines into buckets.

                                                    The buckets are ordered in library provided order of relevancy. You can reorder at your choosing.

                                                    func (*Snapshot) IsRace

                                                    func (s *Snapshot) IsRace() bool

                                                      IsRace returns true if a race detector stack trace was found.

                                                      Otherwise, it is a normal goroutines snapshot.

                                                      When a race condition was detected, it is preferable to not call Aggregate().

                                                      func (*Snapshot) ToHTML

                                                      func (s *Snapshot) ToHTML(w io.Writer, footer template.HTML) error

                                                        ToHTML formats the snapshot as HTML to the writer.

                                                        Use footer to add custom HTML at the bottom of the page.

                                                        type Stack

                                                        type Stack struct {
                                                        	// Calls is the call stack. First is original function, last is leaf
                                                        	// function.
                                                        	Calls []Call
                                                        	// Elided is set when there's >100 items in Stack, currently hardcoded in
                                                        	// package runtime.
                                                        	Elided bool
                                                        	// contains filtered or unexported fields
                                                        }

                                                          Stack is a call stack.

                                                          Directories

                                                          Path Synopsis
                                                          Package webstack provides a http.HandlerFunc that serves a snapshot similar to net/http/pprof.Index().
                                                          Package webstack provides a http.HandlerFunc that serves a snapshot similar to net/http/pprof.Index().