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 SetContext(setter ContextSetter, frames []model.StacktraceFrame, pre, post int) error
• func SplitFunctionName(in string) (packagePath, function string)
• type ContextSetter
  • func FileSystemContextSetter(fs http.FileSystem) ContextSetter
• type Frame
  • func AppendCallerFrames(frames []Frame, callers []uintptr) []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 SetContext

func SetContext(setter ContextSetter, frames []model.StacktraceFrame, pre, post int) error

SetContext sets the source context for the given stack frames, with the specified number of pre- and post- lines.

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 ContextSetter

type ContextSetter interface {
	// SetContext sets the source context for the given stack frame,
	// with the specified number of pre- and post- lines.
	SetContext(frame *model.StacktraceFrame, pre, post int) error
}

ContextSetter is an interface that can be used for setting the source context for a stack frame.

func FileSystemContextSetter

func FileSystemContextSetter(fs http.FileSystem) ContextSetter

FileSystemContextSetter returns a ContextSetter that sets context by reading file contents from the provided http.FileSystem.

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) []Frame

AppendCallerFrames appends to frames for the PCs in callers, and returns the extended slice.

See RuntimeFrame for information on what details are included.

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.