stacktrace

Documentation

Overview

Package stacktrace provides a simplified stack frame type, functions for obtaining stack frames, and related utilities.

Index

• func IsLibraryPackage(pkg string) bool
• func RegisterApplicationPackage(pkg ...string)
• func RegisterLibraryPackage(pkg ...string)
• func SplitFunctionName(in string) (packagePath, function string)
• type Frame
  • func AppendCallerFrames(frames []Frame, callers []uintptr, n int) []Frame
  • func AppendErrorStacktrace(frames []Frame, err error, n int) []Frame
  • func AppendStacktrace(frames []Frame, skip, n int) []Frame
  • func RuntimeFrame(in runtime.Frame) Frame

Functions

func IsLibraryPackage

func IsLibraryPackage(pkg string) bool

IsLibraryPackage reports whether or not the given package path is a library package. This includes known library packages (e.g. stdlib or apm-agent-go), vendored packages, and any packages with a prefix registered with RegisterLibraryPackage but not RegisterApplicationPackage.

func RegisterApplicationPackage

func RegisterApplicationPackage(pkg ...string)

RegisterApplicationPackage registers the given packages as being an application path. This must not be called concurrently with any other functions or methods in this package; it is expected to be used by init functions.

It is not typically necessary to register application paths. If a package does not match a registered *library* package path prefix, then the path is considered an application path. This function exists for the unusual case that an application exists within a library (e.g. an example program).

func RegisterLibraryPackage

func RegisterLibraryPackage(pkg ...string)

RegisterLibraryPackage registers the given packages as being well-known library path prefixes. This must not be called concurrently with any other functions or methods in this package; it is expected to be used by init functions.

func SplitFunctionName

func SplitFunctionName(in string) (packagePath, function string)

SplitFunctionName splits the function name as formatted in runtime.Frame.Function, and returns the package path and function name components.

Types

type Frame

type Frame struct {
	// File is the filename of the location of the stack frame.
	// This may be either the absolute or base name of the file.
	File string

	// Line is the 1-based line number of the location of the
	// stack frame, or zero if unknown.
	Line int

	// Function is the name of the function name for this stack
	// frame. This should be package-qualified, and may be split
	// using stacktrace.SplitFunctionName.
	Function string
}

Frame describes a stack frame.

func AppendCallerFrames

func AppendCallerFrames(frames []Frame, callers []uintptr, n int) []Frame

AppendCallerFrames appends to n frames for the PCs in callers, and returns the extended slice. If n is negative, all available frames will be added. Multiple frames may exist for the same caller/PC in the case of function call inlining.

See RuntimeFrame for information on what details are included.

func AppendErrorStacktrace

func AppendErrorStacktrace(frames []Frame, err error, n int) []Frame

AppendErrorStacktrace appends at most n entries extracted from err to frames, and returns the extended slice. If n is negative, then all stack frames will be appended.

func AppendStacktrace

func AppendStacktrace(frames []Frame, skip, n int) []Frame

AppendStacktrace appends at most n entries to frames, skipping skip frames starting with AppendStacktrace, and returns the extended slice. If n is negative, then all stack frames will be appended.

See RuntimeFrame for information on what details are included.

func RuntimeFrame

func RuntimeFrame(in runtime.Frame) Frame

RuntimeFrame returns a Frame based on the given runtime.Frame.

The resulting Frame will have the file path, package-qualified function name, and line number set. The function name can be split using SplitFunctionName, and the absolute path of the file and its base name can be determined using standard filepath functions.