stack

Documentation

Overview

Package stack provides utilities for capturing and formatting Go call stacks. It wraps runtime stack information with convenient formatting and manipulation capabilities.

This package is originally based on github.com/go-stack/stack, but has been significantly modified and rewritten.

Package stack provides utilities for capturing and formatting Go call stacks.

This file contains trace related functionality, originally based on github.com/go-stack/stack.

Index

• Constants
• Variables
• func GetPC(skip int) uintptr
• type Call
  • func CallFromPC(pc uintptr) Call
  • func Caller(skip int) Call
  • func (c Call) Format(s fmt.State, verb rune)
  • func (c Call) Frame() runtime.Frame
  • func (c Call) IsZero() bool
  • func (c Call) MarshalText() ([]byte, error)
  • func (c Call) String() string
• type CallStack
  • func Trace(skip int) CallStack
  • func (cs CallStack) Describe(w io.Writer, format string, sep string) (n int, err error)
  • func (cs CallStack) Format(s fmt.State, verb rune)
  • func (cs CallStack) MarshalText() ([]byte, error)
  • func (cs CallStack) String() string
  • func (cs CallStack) TrimAbove(c Call) CallStack
  • func (cs CallStack) TrimBelow(c Call) CallStack
  • func (cs CallStack) TrimRuntime() CallStack

Constants

const TraceFullFmt = "%[1]n\t%+[1]v"

TraceFullFmt is a format string for detailed stack trace output. It displays the full function name and location for each frame. Usage: cs.Describe(w, stack.TraceFullFmt, "\n")

Variables

var ErrNoFunc = errors.New("no call stack information")

ErrNoFunc means that the Call has a nil *runtime.Func. The most likely cause is a Call with the zero value.

Functions

func GetPC

func GetPC(skip int) uintptr

GetPC returns the program counter for the caller at the specified skip level. The skip parameter works the same as in Caller. This can be more efficient than Caller when you only need the PC value.

Types

type Call

type Call struct {
	// contains filtered or unexported fields
}

Call records a single function invocation from a goroutine stack. It wraps runtime.Frame with convenient formatting methods.

func CallFromPC

func CallFromPC(pc uintptr) Call

CallFromPC creates a Call from a program counter value. This is useful when you have a PC from GetPC or other sources.

func Caller

func Caller(skip int) Call

Caller returns a Call from the stack of the current goroutine. The argument skip is the number of stack frames to ascend, with 0 identifying the calling function.

Example:

func myFunc() {
    call := stack.Caller(0) // captures myFunc
    call := stack.Caller(1) // captures myFunc's caller
}

func (Call) Format

func (c Call) Format(s fmt.State, verb rune)

Format implements fmt.Formatter with support for the following verbs.

%s    source file
%d    line number
%n    function name
%k    last segment of the package path
%v    equivalent to %k/%s:%d

It accepts the '+' and '#' flags for most of the verbs as follows.

%+s   path of source file relative to the compile time GOPATH,
      or the module path joined to the path of source file relative
      to module root
%#s   full path of source file
%+n   import path qualified function name
%+k   full package path
%+v   equivalent to %+k/%s:%d
%#v   equivalent to %#s:%d

func (Call) Frame

func (c Call) Frame() runtime.Frame

Frame returns the call frame information for the Call.

func (Call) IsZero

func (c Call) IsZero() bool

IsZero reports whether the Call is empty (zero value).

func (Call) MarshalText

func (c Call) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It formats the Call the same as fmt.Sprintf("%v", c).

func (Call) String

func (c Call) String() string

String implements fmt.Stringer. It is equivalent to fmt.Sprintf("%v", c).

type CallStack

type CallStack []Call

CallStack represents a sequence of function invocations from a goroutine stack. It can be formatted using various fmt verbs for different output formats.

func Trace

func Trace(skip int) CallStack

Trace captures the call stack of the current goroutine and returns it as a CallStack. The skip parameter indicates how many stack frames to skip, with element 0 identifying the calling function.

Example:

func myFunc() {
    cs := stack.Trace(0) // captures from myFunc onwards
    fmt.Printf("%+v", cs) // prints formatted stack trace
}

func (CallStack) Describe

func (cs CallStack) Describe(w io.Writer, format string, sep string) (n int, err error)

Describe writes each Call in the CallStack to w using the specified format string and separator. The format parameter is applied to each Call using fmt.Fprintf. Returns the total number of bytes written and any error encountered.

Example:

cs.Describe(os.Stdout, "%n\t%+v", "\n") // function name and location on each line

func (CallStack) Format

func (cs CallStack) Format(s fmt.State, verb rune)

Format implements fmt.Formatter by printing the CallStack as square brackets ([, ]) surrounding a tab separated list of Calls each formatted with the supplied verb and options.

func (CallStack) MarshalText

func (cs CallStack) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It formats the CallStack the same as fmt.Sprintf("%v", cs).

func (CallStack) String

func (cs CallStack) String() string

String implements fmt.Stringer. It is equivalent to fmt.Sprintf("%v", cs).

func (CallStack) TrimAbove

func (cs CallStack) TrimAbove(c Call) CallStack

TrimAbove returns a slice of the CallStack with all entries above c removed.

func (CallStack) TrimBelow

func (cs CallStack) TrimBelow(c Call) CallStack

TrimBelow returns a slice of the CallStack with all entries below c removed.

func (CallStack) TrimRuntime

func (cs CallStack) TrimRuntime() CallStack

TrimRuntime returns a slice of the CallStack with the topmost entries from the Go runtime removed. It considers any calls originating from unknown files, files under GOROOT, or _testmain.go as part of the runtime. This is useful for getting cleaner stack traces that focus on application code.