stacktrace

Documentation

Overview

Package stacktrace provides efficient stack trace capture and formatting for Go programs.

This package captures the call stack of the current goroutine with configurable depth and skip parameters, allowing precise control over which frames are recorded.

Basic Usage

To capture the current stack trace:

stack := stacktrace.CaptureStack(0, stacktrace.DefaultDepth)
fmt.Println(stack.String())

To capture only the immediate caller:

frame := stacktrace.CaptureCaller(0)
fmt.Println(frame.FullPath()) // prints: /path/to/file.go:123

Frame Type

The Frame type represents a single stack frame with program counter, file path, line number, and function name. It provides several formatting methods:

frame := stacktrace.CaptureCaller(0)
frame.FullPath()  // Returns: "/path/to/file.go:123"
frame.String()    // Returns: "function.name\n\t/path/to/file.go:123"

Use CaptureCaller when you only need information about the immediate caller, as it's more efficient than capturing a full stack trace.

Controlling Depth

Capture a limited number of frames:

stack := stacktrace.CaptureStack(0, 10) // Capture up to 10 frames

Capture the complete stack trace:

stack := stacktrace.CaptureStack(0, math.MaxInt) // Unlimited depth

Skipping Frames

Skip frames to exclude wrapper functions from the trace:

func myLogger(msg string) {
    // Skip 1 frame to exclude myLogger from the trace
    stack := stacktrace.CaptureStack(1, stacktrace.DefaultDepth)
    log.Printf("%s\n%s", msg, stack.String())
}

The same skip parameter works with CaptureCaller:

func getCallerInfo() string {
    // Skip 1 to get the caller of getCallerInfo, not getCallerInfo itself
    frame := stacktrace.CaptureCaller(1)
    return frame.FullPath()
}

Output Format

The Stack.String() method formats stack traces as:

function.name
	/path/to/file.go:123
another.function
	/path/to/other.go:456

This format is compact and easy to parse, with each frame showing the fully-qualified function name followed by the source location on the next line, indented with a tab.

Iterating Over Frames

Access individual frames using the iterator for custom processing or formatting:

stack := stacktrace.CaptureStack(0, stacktrace.DefaultDepth)
for idx, frame := range stack.Frames() {
    fmt.Printf("%d: %s at %s:%d\n", idx, frame.Function, frame.File, frame.Line)
}

Index

• Constants
• type Frame
  • func CaptureCaller(skip int) Frame
  • func NewFrame(f runtime.Frame) Frame
  • func (f Frame) FullPath() string
  • func (f Frame) String() string
  • func (f Frame) Write(b *bytes.Buffer)
  • func (f Frame) WriteFullPath(b *bytes.Buffer)
• type Stack
  • func CaptureStack(skip, depth int) *Stack
  • func (s *Stack) Frames() iter.Seq2[int, Frame]
  • func (s *Stack) Len() int
  • func (s *Stack) String() string

Constants

const DefaultDepth = 64

DefaultDepth is the default maximum number of stack frames to capture.

Types

type Frame

type Frame struct {
	// PC is the program counter for this frame.
	PC uintptr
	// File is the full path to the source file.
	File string
	// Line is the line number in the source file.
	Line int
	// Function is the name of the function.
	Function string
}

Frame represents a single stack frame containing program counter, file path, line number, and function name.

This is a simplified representation of runtime.Frame that is safe to store and use after the stack trace has been captured.

func CaptureCaller

func CaptureCaller(skip int) Frame

CaptureCaller captures a single caller frame from the current goroutine's call stack. The skip argument specifies the number of frames to skip before recording (0 means the direct caller of CaptureCaller).

This is more efficient than CaptureStack when only the immediate caller information is needed, as it only captures and processes a single frame.

func NewFrame

func NewFrame(f runtime.Frame) Frame

NewFrame creates a Frame from a runtime.Frame, copying the essential fields.

func (Frame) FullPath

func (f Frame) FullPath() string

FullPath returns the full file path and line number formatted as "/path/to/file:line". Returns "undefined" if the frame has a zero PC.

func (Frame) String

func (f Frame) String() string

String returns a formatted representation of the frame including function name and source location. Returns "undefined" if the frame has a zero PC.

func (Frame) Write

func (f Frame) Write(b *bytes.Buffer)

Write writes the function name and source location of the frame to the provided buffer in the format "function\n\t/path/to/file:line". If the PC is zero, it writes "undefined".

func (Frame) WriteFullPath

func (f Frame) WriteFullPath(b *bytes.Buffer)

WriteFullPath writes the full file path and line number of the frame to the provided buffer in the format "/path/to/file:line". If the PC is zero, it writes "undefined".

type Stack

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

Stack represents a captured call stack consisting of program counter frames.

func CaptureStack

func CaptureStack(skip, depth int) *Stack

CaptureStack captures the current goroutine's call stack. The skip argument specifies the number of frames to skip before recording (0 means start at caller). The depth argument specifies the maximum number of frames to capture (use math.MaxInt for unlimited).

func (*Stack) Frames

func (s *Stack) Frames() iter.Seq2[int, Frame]

Frames returns an iterator over the stack frames. The iterator yields (index, frame) pairs for each frame in the stack.

func (*Stack) Len

func (s *Stack) Len() int

Len returns the number of frames in the stack trace.

func (*Stack) String

func (s *Stack) String() string

String formats the stack trace as a multi-line string with function names and source locations. Each frame is formatted as "function\n\tfile:line".