README

GoDoc Go Report Card TravisCI Coverage Status

stack

Package stack implements utilities to capture, manipulate, and format call stacks. It provides a simpler API than package runtime.

The implementation takes care of the minutia and special cases of interpreting the program counter (pc) values returned by runtime.Callers.

Versioning

Package stack publishes releases via semver compatible Git tags prefixed with a single 'v'. The master branch always contains the latest release. The develop branch contains unreleased commits.

Formatting

Package stack's types implement fmt.Formatter, which provides a simple and flexible way to declaratively configure formatting when used with logging or error tracking packages.

func DoTheThing() {
    c := stack.Caller(0)
    log.Print(c)          // "source.go:10"
    log.Printf("%+v", c)  // "pkg/path/source.go:10"
    log.Printf("%n", c)   // "DoTheThing"

    s := stack.Trace().TrimRuntime()
    log.Print(s)          // "[source.go:15 caller.go:42 main.go:14]"
}

See the docs for all of the supported formatting options.

Expand ▾ Collapse ▴

Documentation

Overview

    Package stack implements utilities to capture, manipulate, and format call stacks. It provides a simpler API than package runtime.

    The implementation takes care of the minutia and special cases of interpreting the program counter (pc) values returned by runtime.Callers.

    Package stack's types implement fmt.Formatter, which provides a simple and flexible way to declaratively configure formatting when used with logging or error tracking packages.

    Example (CallFormat)
    Output:
    
    github.com/go-stack/stack/format_test.go
    format_test.go:13   Example_callFormat()
    

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    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

      This section is empty.

      Types

      type Call

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

        Call records a single function invocation from a goroutine stack.

        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.

          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 %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 %+s:%d
            %#v   equivalent to %#s:%d
            

            func (Call) Frame

            func (c Call) Frame() runtime.Frame

              Frame returns the call frame infomation for the Call.

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

                func (c Call) PC() uintptr

                  PC returns the program counter for this call frame; multiple frames may have the same PC value.

                  Deprecated: Use Call.Frame instead.

                  func (Call) String

                  func (c Call) String() string

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

                    type CallStack

                    type CallStack []Call

                      CallStack records a sequence of function invocations from a goroutine stack.

                      func Trace

                      func Trace() CallStack

                        Trace returns a CallStack for the current goroutine with element 0 identifying the calling function.

                        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 space 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.Stinger. 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.

                                    Source Files