stack

Stack Module

The stack module provides utilities for stack trace analysis and caller identification, enabling detailed debugging and error reporting capabilities.

Features

• Runtime Stack Trace Capture: Efficient capture of runtime stack traces
• Caller Identification: Accurate identification of calling functions
• Stack Frame Analysis: Detailed analysis of stack frames with metadata
• Performance Optimization: Cached stack trace processing for minimal overhead
• Go Runtime Integration: Deep integration with Go's runtime internals

Installation

go get github.com/pubgo/funk/v2/stack

Quick Start

Basic Stack Trace Capture

import "github.com/pubgo/funk/v2/stack"

// Capture current stack trace
frames := stack.Trace()

// Print stack frames
for _, frame := range frames {
    fmt.Printf("%s\n", frame.String())
}

Caller Identification

import "github.com/pubgo/funk/v2/stack"

// Get immediate caller
caller := stack.Caller(0)
fmt.Printf("Called from: %s:%d %s\n", caller.File, caller.Line, caller.Name)

// Get parent caller
parent := stack.Caller(1)
fmt.Printf("Parent caller: %s:%d %s\n", parent.File, parent.Line, parent.Name)

Function-Based Caller Identification

import "github.com/pubgo/funk/v2/stack"

func myFunction() {
    // Get caller of this function
    caller := stack.CallerWithFunc(myFunction)
    fmt.Printf("myFunction called from: %s\n", caller.String())
}

Core Concepts

Stack Frames

The module represents stack frames with detailed metadata:

type Frame struct {
    Name string // Function name
    Pkg  string // Package path
    File string // File path
    Line int    // Line number
}

Stack Trace Capture

Capture full stack traces for debugging:

// Capture complete stack trace
frames := stack.Trace()

// Process frames
for _, frame := range frames {
    if frame.IsRuntime() {
        continue  // Skip runtime frames
    }
    fmt.Printf("File: %s, Line: %d, Function: %s\n", 
        frame.File, frame.Line, frame.Name)
}

Caller Identification

Identify specific callers with configurable skip levels:

// Caller(0) - current function
// Caller(1) - caller of current function
// Caller(2) - caller's caller, etc.

func example() {
    // This will return information about whoever called example()
    caller := stack.Caller(1)
    fmt.Printf("Called from %s:%d\n", caller.File, caller.Line)
}

Advanced Usage

Selective Stack Capture

import "github.com/pubgo/funk/v2/stack"

// Capture specific number of frames
frames := stack.Callers(10)  // Capture up to 10 frames

// Capture frames with skip
frames := stack.Callers(5, 2)  // Skip 2 frames, then capture 5

Stack Frame Filtering

import (
    "github.com/pubgo/funk/v2/stack"
    "github.com/samber/lo"
)

// Filter out runtime frames
frames := lo.Filter(stack.Trace(), func(frame *stack.Frame, _ int) bool {
    return !frame.IsRuntime()
})

// Filter by package
appFrames := lo.Filter(frames, func(frame *stack.Frame, _ int) bool {
    return strings.HasPrefix(frame.Pkg, "github.com/mycompany/myapp")
})

Frame Formatting

import "github.com/pubgo/funk/v2/stack"

frame := stack.Caller(0)

// Full format
fmt.Printf("Full: %s\n", frame.String())  // /path/to/file.go:123 FunctionName

// Short format
fmt.Printf("Short: %s\n", frame.Short())  // file.go:123 FunctionName

Performance Optimization

The module uses caching to optimize repeated stack operations:

// Repeated calls to stack functions benefit from internal caching
for i := 0; i < 1000; i++ {
    caller := stack.Caller(0)  // Cached after first call
    // Process caller
}

API Reference

Core Functions

Frame Methods

Utility Functions

Best Practices

1. Use Appropriate Skip Levels: Choose correct skip levels for accurate caller identification
2. Filter Runtime Frames: Remove runtime frames for cleaner stack traces
3. Cache When Possible: Leverage built-in caching for repeated operations
4. Limit Depth: Use appropriate stack depth to avoid performance issues
5. Contextual Information: Include relevant contextual information in error reports

Integration Patterns

With Error Handling

import (
    "github.com/pubgo/funk/v2/stack"
    "github.com/pubgo/funk/v2/errors"
)

func wrapWithErrorContext() error {
    caller := stack.Caller(1)
    err := someOperation()
    if err != nil {
        // Wrap error with caller context
        return errors.Wrapf(err, "failed at %s:%d in %s", 
            caller.File, caller.Line, caller.Name)
    }
    return nil
}

With Logging

import (
    "github.com/pubgo/funk/v2/stack"
    "github.com/pubgo/funk/v2/log"
)

func logWithContext() {
    caller := stack.Caller(0)
    logger := log.GetLogger("stack")
    
    logger.Info().
        Str("file", caller.File).
        Int("line", caller.Line).
        Str("function", caller.Name).
        Msg("Operation performed")
}

With Debugging Tools

import (
    "github.com/pubgo/funk/v2/stack"
    "github.com/pubgo/funk/v2/log"
)

func debugFunction() {
    // Capture stack for debugging
    frames := stack.Trace()
    
    logger := log.GetLogger("debug")
    for i, frame := range frames {
        if i > 10 {  // Limit output
            break
        }
        if frame.IsRuntime() {
            continue
        }
        logger.Debug().Msgf("Stack frame %d: %s", i, frame.String())
    }
}