crash

README

crash

Build Status

Overview

Crash is a Go package which provides facilities for executing custom code during panic/crash situations. This can be used to enable crash forensics and crash reporting features in an application.

License

This Go package is release under a BSD-style license, the contents of which are in the repo's LICENSE file.

API Documentation

http://godoc.org/github.com/xaevman/crash

Documentation

Overview

Package crash provides some basic services to help handle logging and reporting of application panics/crashes.

Index

• Constants
• func AddHandler(newHandler CrashHandler)
• func HandleAll()
• func SetRepanic(val bool)
• func SetVerboseCrashReport(val bool)
• type CrashHandler
• type CrashReport
  • func NewCrashReport(errData interface{}) *CrashReport
  • func (this *CrashReport) Json() ([]byte, error)
• type EmailHandler
  • func NewEmailHandler() *EmailHandler
  • func (this *EmailHandler) ClearToAddrs()
  • func (this *EmailHandler) OnCrash(data interface{})
• type FileHandler
  • func (this *FileHandler) OnCrash(data interface{})
  • func (this *FileHandler) SetCrashDir(path string) error
• type StackFrame
• type StackTrace
  • func NewStackTrace() []*StackTrace
• type TerseMemStats

Constants

const STACK_BUFFERS = 2 * 1024

Maximum number of stack records to hold.

Functions

func AddHandler

func AddHandler(newHandler CrashHandler)

AddHandler adds a new crash handler to be used by the HandleCrashes function when a panic recovery occurs. Handlers are called in the order they are registered.

func HandleAll

func HandleAll()

HandleAll should be defered as a part of calling a new goroutine in order to handle panics that occur within that routine. Crash handlers are called in the order they were registered.

func SetRepanic

func SetRepanic(val bool)

SetRepanic sets the re-panic mode. With re-panic disabled, HandleCrashes will exit cleanly after all crash handlers have been run. When enabled, HandleCrashes "re-throws" the current panic after all crash handlers have been run. The default vaule is true.

func SetVerboseCrashReport

func SetVerboseCrashReport(val bool)

SetVerboseCrashReport determines whether or not verbose crash reports are generated. The default value is false.

Types

type CrashHandler

type CrashHandler interface {
	OnCrash(interface{})
}

CrashHandler represents the interface which must be implemented by custom crash handling objects.

type CrashReport

type CrashReport struct {
	Timestamp   time.Time
	ErrData     interface{}
	AppName     string
	AppPath     string
	GoOS        string
	GoArch      string
	CPUCount    int
	HostName    string
	WorkingDir  string
	MemStats    interface{}
	Environment []string
	StackTrace  []*StackTrace
}

CrashReport represents important information which is generated during a crash.

func NewCrashReport

func NewCrashReport(errData interface{}) *CrashReport

NewCrashReport generates a new CrashReport object, fills it in with information about the current system state, and returns a reference to the new object back to the caller.

func (*CrashReport) Json

func (this *CrashReport) Json() ([]byte, error)

Json returns the JSON representation of this CrashReport object.

type EmailHandler

type EmailHandler struct {
	FromAddr string
	ToAddrs  []string
	SrvAddr  string
	SrvPort  int
	SrvUser  string
	SrvPass  string
}

EmailHandler is a CrashHandler implementation which generates a crash report from the given panic data, formats in JSON format, and sends it to the configured email addresses via the configured smtp server.

func NewEmailHandler

func NewEmailHandler() *EmailHandler

NewEmailHandler returns a pointer to a new EmailHandler instance with its values fully intialized.

func (*EmailHandler) ClearToAddrs

func (this *EmailHandler) ClearToAddrs()

ClearToAddrs clears the list of To addresses on the EmailHandler.

func (*EmailHandler) OnCrash

func (this *EmailHandler) OnCrash(data interface{})

OnCrash is called automatically by the global crash handling routines. OnCrash creates a new JSON crash report email and sends it to the configured recipients.

type FileHandler

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

FileHandler is a CrashHandler implementation which generates a crash report from the given panic data, formats it in JSON format, and saves it to a flat flie on disk.

func (*FileHandler) OnCrash

func (this *FileHandler) OnCrash(data interface{})

OnCrash is called automatically by the global crash handling routines. OnCrash creates a new JSON crash report file in the configured crash directory with the filename format "crash.<unix timestamp>.json".

func (*FileHandler) SetCrashDir

func (this *FileHandler) SetCrashDir(path string) error

SetCrashDir reconfigures the CrashHandler to save files to a new base path. The new base path is automatically created if it doesn't already exist. Any errors from the underlying mkdir call are passed back to the caller.

type StackFrame

type StackFrame struct {
	File string
	Line int
	Name string
}

StackFrame represents the function name, file and line number information for a given frame within a stack trace.

type StackTrace

type StackTrace struct {
	Id     int
	Frames []*StackFrame
}

StackTrace represents the collection of stack frame data associated with a single goroutine.

func NewStackTrace

func NewStackTrace() []*StackTrace

NewStackTrace is a constructor function which queries the Go runtime for goroutine information and builds a StackTrace object for each. A slice of StackTraces, one for each running goroutine, is returned.

type TerseMemStats

type TerseMemStats struct {
	Alloc         uint64
	Mallocs       uint64
	Frees         uint64
	HeapIdle      uint64
	HeapInuse     uint64
	HeapObjects   uint64
	StackInuse    uint64
	NumGC         uint32
	GCCPUFraction float64
	EnableGC      bool
	DebugGC       bool
}

TerseMemStats represents a subset of the information normally provided in a runtime.MemStats structure.