stacktrace

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2026 License: MIT Imports: 4 Imported by: 9

README

Stack Trace Implementation for Go

This repository provides a comprehensive stack trace implementation for Go, allowing for detailed error handling and reporting. It includes features such as error wrapping, severity levels, and position tracking.

Features

  • Error Wrapping: Wrap errors with additional context.
  • Severity Levels: Define the severity of errors.
  • Position Tracking: Track the position (line and column) of errors in files.
  • Trace Options: Customize trace generation with options like ensuring duplicates are not printed.

Installation

To install the package, use:

go get github.com/acronis/go-stacktrace

Usage

Basic usage

package main

import (
    "fmt"
    "github.com/acronis/go-stacktrace"
)

func main() {
    err := stacktrace.New("An error occurred", stacktrace.WithLocation("/path/to/file"), stacktrace.WithPosition(stacktrace.NewPosition(10, 1)))
    fmt.Println(err)
    // Output:
    // /path/to/file:10:1: An error occurred
}

Wrapping errors

package main

import (
    "fmt"
    "github.com/acronis/go-stacktrace"
)

func main() {
    baseErr := fmt.Errorf("base error")
    wrappedErr := stacktrace.NewWrapped("an error occurred", baseErr, stacktrace.WithLocation("/path/to/file"), stacktrace.WithPosition(stacktrace.NewPosition(10, 1)))
    fmt.Println(wrappedErr)
    // Output:
    // /path/to/file:10:1: an error occurred: base error
    
    unwrappedErr, ok := stacktrace.Unwrap(wrappedErr)
    if ok {
        fmt.Println(unwrappedErr)
    }
    
    wrappedErr2 := stacktrace.Wrap(baseErr, stacktrace.WithLocation("/path/to/file"), stacktrace.WithPosition(stacktrace.NewPosition(10, 1)))
    fmt.Println(wrappedErr2)
    // Output:
    // /path/to/file:10:1: base error
}

Customizing Traces

package main

import (
    "fmt"
    "github.com/acronis/go-stacktrace"
)

func main() {
    err := stacktrace.New("an error occurred", stacktrace.WithLocation("/path/to/file"), stacktrace.WithPosition(stacktrace.NewPosition(10, 1)))
    traces := err.GetTraces(stacktrace.WithEnsureDuplicates())
    fmt.Println(traces)
}

API

Types
  • StackTrace: Represents a stack trace with various attributes.
  • Severity: Represents the severity level of an error.
  • Type: Represents the type of an error.
  • Position: Represents the position (line and column) of an error in a file.
  • Location: Represents the location (file path) of an error.
Functions
  • New(message string, opts ...Option) *StackTrace: Creates a new stack trace.
  • NewWrapped(message string, err error, opts ...Option) *StackTrace: Creates a new wrapped stack trace.
  • Wrap(err error, opts ...Option) *StackTrace: Wraps an existing error in a stack trace.
  • Unwrap(err error) (*StackTrace, bool): Unwraps a stack trace from an error.
Options
  • WithLocation(location string) Option: Sets the location of the error.
  • WithSeverity(severity Severity) Option: Sets the severity of the error.
  • WithPosition(position *Position) Option: Sets the position of the error.
  • WithInfo(key string, value fmt.Stringer) Option: Adds additional information to the error.
  • WithType(errType Type) Option: Sets the type of the error.
  • WithEnsureDuplicates() TracesOpt: Ensures that duplicates are not printed in traces.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Documentation

Index

Constants

View Source 
const ChainTruncatedMsg = "error chain truncated"

ChainTruncatedMsg is the message of the sentinel leaf substituted for the Wrapped chain when MaxDepth is exceeded.

View Source 
const TooManyErrorsMsg = "too many errors, some have been omitted"

TooManyErrorsMsg is the message of the sentinel entry added to List when MaxList is exceeded. Callers can test for this to detect truncation.

Variables

View Source 
var MaxDepth = 2000

MaxDepth is the maximum Wrapped-chain depth. When the incoming node's depth equals or exceeds this limit, the chain is replaced by a sentinel leaf. A value of 0 means unlimited.

View Source 
var MaxList = 10

MaxList is the maximum number of entries allowed in a StackTrace's List. When the limit is reached, a sentinel entry is appended and further entries are dropped. A value of 0 means unlimited.

Functions

func Stringer 

func Stringer(v interface{}) fmt.Stringer

Stringer returns a fmt.Stringer for the given value.

Types

type Accumulator added in v0.7.0 

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

Accumulator collects multiple *StackTrace errors into a single List-bearing root node. The zero value is ready to use without any initialization.

It replaces the repetitive nil-check-then-Append pattern: 

var acc stacktrace.Accumulator
for _, item := range items {
	if err := process(item); err != nil {
		acc.Add(stacktrace.NewWrapped("step", err))
	}
}
return acc.Result()

func (*Accumulator) Add added in v0.7.0 

func (a *Accumulator) Add(st *StackTrace)

Add appends st to the accumulator. A nil st is ignored.

func (*Accumulator) Result added in v0.7.0 

func (a *Accumulator) Result() *StackTrace

Result returns the accumulated StackTrace, or nil when no errors were added.

type Location 

type Location string

func (*Location) String 

func (loc *Location) String() string

type Option 

type Option interface {
	Apply(*StackTrace)
}

Option is an option for the StackTrace creation.

func WithInfo 

func WithInfo(key string, value any) Option

func WithLocation 

func WithLocation(location string) Option

WithLocation sets the location of the error.

func WithPosition 

func WithPosition(pos *Position) Option

func WithSeverity 

func WithSeverity(severity Severity) Option

func WithType 

func WithType(errType Type) Option

WithType sets the type of the error with override.

type Position 

type Position struct {
	Line      int
	Column    int
	EndLine   int
	EndColumn int // 1-based exclusive (column after the last character); when set, used to construct a multi-character LSP range
}

Position contains the line and column where the error occurred.

func NewPosition 

func NewPosition(line, column int) *Position

NewPosition creates a new position with the given line and column.

func (*Position) String 

func (p *Position) String() string

type Severity 

type Severity string

Severity is the severity of the error.

func (*Severity) String 

func (s *Severity) String() string

String is a fmt.Stringer implementation.

type Stack 

type Stack struct {
	LinePos  *string
	Severity *Severity
	Message  string
	Type     *Type
}

func NewStack 

func NewStack() *Stack

type StackTrace 

type StackTrace struct {
	// Severity is the severity of the error.
	Severity *Severity
	// Type is the type of the error.
	Type *Type
	// Location is the location file path of the error.
	Location *Location
	// Position is the position of the error in the file.
	Position *Position

	// Wrapped is the error that wrapped by this error.
	Wrapped *StackTrace
	// Err is the underlying error. It is not used for the error message.
	Err error
	// Message is the error message.
	Message string
	// Info is the additional information about the error.
	Info StructInfo

	// List is the list of stack traces.
	List []*StackTrace
	// contains filtered or unexported fields
}

StackTrace contains information about a parser error.

func New 

func New(message string, opts ...Option) *StackTrace

New creates a new StackTrace.

func NewWrapped 

func NewWrapped(message string, err error, opts ...Option) *StackTrace

NewWrapped creates a new StackTrace from the given go error.

func Unwrap 

func Unwrap(err error) (*StackTrace, bool)

Unwrap checks if the given error is a StackTrace and returns it. It returns false if the error is not a StackTrace. if err is a StackTrace, it returns the wrapped StackTrace and true. if err is not a StackTrace, it is unwrapped and wrapped with a new StackTrace if it has a wrapped StackTrace.

func Wrap 

func Wrap(err error, opts ...Option) *StackTrace

Wrap wraps the given error with the StackTrace if it is not a StackTrace. It returns the wrapped StackTrace.

func (*StackTrace) Append 

func (st *StackTrace) Append(e *StackTrace) *StackTrace

Append adds the given StackTrace to the list of StackTraces and returns it. Duplicate entries — those whose (location, position, message, info) fingerprint matches an existing entry — are silently dropped. When MaxList > 0 and the list is full, a TooManyErrorsMsg sentinel is appended in place of the new entry and all subsequent entries are dropped.

func (*StackTrace) Error 

func (st *StackTrace) Error() string

StackTrace implements the error interface. It returns the string representation of the StackTrace.

func (*StackTrace) GetLocWithPos 

func (st *StackTrace) GetLocWithPos() string

GetLocWithPos returns the location with position of the StackTrace.

func (*StackTrace) GetLocWithPosPtr 

func (st *StackTrace) GetLocWithPosPtr() *string

GetLocWithPosPtr returns the location with position of the StackTrace.

func (*StackTrace) GetTraces 

func (st *StackTrace) GetTraces(opts ...TracesOpt) []Trace

func (*StackTrace) Header 

func (st *StackTrace) Header() string

Header returns the header of the StackTrace.

func (*StackTrace) Is 

func (st *StackTrace) Is(err error) bool

Is checks if the given error is the same as the StackTrace.

func (*StackTrace) MessageWithInfo 

func (st *StackTrace) MessageWithInfo() string

func (*StackTrace) OrigString 

func (st *StackTrace) OrigString() string

OrigString returns the original error message without the wrapping messages.

func (*StackTrace) OrigStringW 

func (st *StackTrace) OrigStringW() string

OrigStringW returns the original error message with the wrapped OrigStringW

func (*StackTrace) SetErr 

func (st *StackTrace) SetErr(err error) *StackTrace

SetErr sets the underlying error of the StackTrace and returns it

func (*StackTrace) SetLocation 

func (st *StackTrace) SetLocation(location string) *StackTrace

SetLocation sets the location of the StackTrace and returns it

func (*StackTrace) SetMessage 

func (st *StackTrace) SetMessage(message string, a ...any) *StackTrace

SetMessage sets the message of the StackTrace and returns it

func (*StackTrace) SetPosition 

func (st *StackTrace) SetPosition(pos *Position) *StackTrace

SetPosition sets the position of the StackTrace and returns it

func (*StackTrace) SetSeverity 

func (st *StackTrace) SetSeverity(severity Severity) *StackTrace

SetSeverity sets the severity of the StackTrace and returns it

func (*StackTrace) SetType 

func (st *StackTrace) SetType(t Type) *StackTrace

SetType sets the type of the StackTrace and returns it, operation can be done only once.

func (*StackTrace) String 

func (st *StackTrace) String() string

String implements the fmt.Stringer interface. It returns the string representation of the StackTrace.

func (*StackTrace) Wrap 

func (st *StackTrace) Wrap(w *StackTrace) *StackTrace

Wrap wraps the given StackTrace and returns it. If MaxDepth > 0 and w's chain depth already equals or exceeds MaxDepth, the chain is replaced by a sentinel leaf that carries the message, location, and position of the deepest reachable node so the caller still sees the root cause rather than only ChainTruncatedMsg.

type StructInfo 

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

StructInfo is a map of string keys to fmt.Stringer values. It is used to store additional information about an error. WARNING: Not thread-safe

func NewStructInfo 

func NewStructInfo() *StructInfo

NewStructInfo creates a new struct info.

func (*StructInfo) Add 

func (s *StructInfo) Add(key string, value fmt.Stringer) *StructInfo

Add adds a key-value pair to the struct info.

func (*StructInfo) Get 

func (s *StructInfo) Get(key string) fmt.Stringer

Get returns the value of the given key.

func (*StructInfo) Has 

func (s *StructInfo) Has(key string) bool

Has checks if the given key exists in the struct info.

func (*StructInfo) Keys 

func (s *StructInfo) Keys() []string

Keys returns the keys of the struct info.

func (*StructInfo) Remove 

func (s *StructInfo) Remove(key string) *StructInfo

Remove removes the given key from the struct info.

func (*StructInfo) SortedKeys 

func (s *StructInfo) SortedKeys() []string

SortedKeys returns the sorted keys of the struct info.

func (*StructInfo) String 

func (s *StructInfo) String() string

String implements the fmt.Stringer interface. It returns a string representation of the struct info.

func (*StructInfo) StringBy 

func (s *StructInfo) StringBy(key string) string

StringBy returns the string value of the given key.

func (*StructInfo) Update 

func (s *StructInfo) Update(u *StructInfo) *StructInfo

Update updates the struct info with the given struct info.

type Trace 

type Trace struct {
	Stack []Stack
}

func NewTrace 

func NewTrace() *Trace

type TracesOpt 

type TracesOpt interface {
	Apply(o *TracesOptions)
}

func WithEnsureDuplicates 

func WithEnsureDuplicates() TracesOpt

type TracesOptions 

type TracesOptions struct {
	// EnsureDuplicates ensures that duplicates are not printed
	EnsureDuplicates bool
	// contains filtered or unexported fields
}

func NewTracesOptions 

func NewTracesOptions() *TracesOptions

type Type 

type Type string

Type is the type of the error.

func (*Type) String 

func (t *Type) String() string

String is a fmt.Stringer implementation.

Source Files

View all Source files

Directories

Path Synopsis
slogex module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.