feat: Change stack trace format to match runtime.Stack

[tomoemon]

Summary

Changed the default stack frame formatter to match runtime.Stack() format for better consistency with Go's standard stack traces and to eliminate dependency on source file availability at runtime.

Old Format vs New Format

Old format (required source files at runtime):

file.go:123 (0x456)
    functionName: sourceCodeLine

New format (runtime.Stack compatible):

functionName()
    file.go:123 +0x456

Motivation

The old format had a significant limitation: it attempted to read source files at runtime using os.Open() to display the actual source code line. This caused issues in production environments where:

1. Source files are not available - Deployed binaries typically don't include source code
2. Silent degradation - When source files couldn't be read, the formatter would silently skip the source line, resulting in inconsistent output
3. Missing function names - If the source couldn't be read, function names weren't displayed at all

Example of the problem:

no user exists with the given uid
github.com/example/project/infra/auth.go:85 (0x125e08a)
github.com/example/project/application/service.go:262 (0x1265468)

Notice: No function names or source code lines are visible because the source files weren't available in the deployed environment.

Benefits of New Format

1. Consistent Output

Function names are always displayed, regardless of source file availability:

github.com/example/project/infra.(*AuthClient).GetUser()
    /path/to/auth.go:85 +0x125e08a
github.com/example/project/application.(*Service).Calculate()
    /path/to/service.go:262 +0x1265468

2. Runtime.Stack Compatibility

Matches the exact format used by Go's runtime/debug.Stack(), making it familiar to all Go developers and compatible with existing log parsing tools.

3. No Runtime Dependencies

No longer attempts to read source files at runtime - all information comes from the compiled binary's debug symbols.

4. Cleaner Output

More concise format that's easier to read in logs:

• Function name on first line
• File path and offset on indented second line

Changes

Code Changes

stackframe_formatter.go:

// Old implementation
func defaultStackFrameFormatter(frame *StackFrame) string {
    str := fmt.Sprintf("%s:%d (0x%x)\n", frame.File, frame.LineNumber, frame.ProgramCounter)
    source, err := frame.SourceLine()  // ❌ Tries to read source file
    if err != nil {
        return str
    }
    return str + fmt.Sprintf("\t%s: %s\n", frame.Name, source)
}

// New implementation
func defaultStackFrameFormatter(frame *StackFrame) string {
    // Format: FunctionName()
    //     file/path.go:123 +0xhex
    return fmt.Sprintf("%s()\n\t%s:%d +0x%x\n", 
        frame.Name, frame.File, frame.LineNumber, frame.ProgramCounter)
}

README.md:

• Updated all stack trace examples to show new format
• Updated format documentation
• All output examples now show function names

Example Output

Before (in production, source unavailable):

database error
/path/to/file.go:42 (0x1234567)
/path/to/file.go:30 (0x7654321)

After:

database error
main.myFunction()
    /path/to/file.go:42 +0x1234567
main.main()
    /path/to/file.go:30 +0x7654321

Testing

All existing tests pass with the new format:

$ go test ./...
ok      github.com/tomoemon/go-errstk          0.276s
ok      github.com/tomoemon/go-errstk/errstklint    0.667s

Backwards Compatibility

This is a format change that affects the string representation of stack traces. Users who:

• Parse stack traces programmatically may need to update their parsers
• Can customize the format using DefaultStackFrameFormatter if they need the old behavior
• Can still access all stack frame data via WalkStack() API for custom formatting

🤖 Generated with Claude Code