panicwatch

README

panicwatch

Simple utility for catching panics in your Go applications.

When you start panicwatch, it creates a new process which watches your application. When the application exits, panicwatch parses the stderr output of your application and if it finds a panic, it will report it using configured callback. Panicwatch doesn't block usage of stderr of your application in any way as it uses dup to get a copy of it.

Panicwatch isn't meant for recovery from panics, but merely for safe and reliable logging when they happen.

Panicwatch won't stand in your way: it won't prevent you from any signal handling/manipulation, other file descriptor magic on your side, or anything that you can think of. It is completely transparent to your application.

Try using it via grongor/go-bootstrap: a library that handles all the annoying bootstrapping for you (config, signals, logging, application context, ...).

package main

import (
	"log"

	"github.com/getsentry/sentry-go"
	"github.com/grongor/panicwatch"
)

func main() {
	if err := sentry.Init(); err != nil {
		log.Fatalln("sentry.Init: " + err.Error())
	}

	app := &yourApp{}

	err := panicwatch.Start(panicwatch.Config{
		OnPanic: func(p panicwatch.Panic) {
			sentry.Log("panic: "+p.Message, "stack", p.Stack)
		},
		OnWatcherDied: func(err error) {
			log.Println("panicwatch watcher process died")
			app.ShutdownGracefully()
		},
	})
	if err != nil {
		log.Fatalln("failed to start panicwatch: " + err.Error())
	}

	app.Start()
}

Documentation

Overview

Package panicwatch guarantees you that you will never miss a panic. Use it to reliably log any unhandled panics that may occur in your application. This is completely transparent to your application, and it doesn't affect it in any way. All signal handling and file descriptor manipulation (either from inside or outside) is still under your control.

Index

• func Start(config Config) error
• type Config
• type Panic
  • func (p Panic) AsError() error
• type PanicType

Functions

func Start

func Start(config Config) error

Start validates panicwatch config, replaces the stderr file descriptor with a new one and starts a watcher process. This watcher process will read the original stderr and tee it into the replaced file descriptor. When the application exits, the watcher process will check if there was a panic in the original stderr. If yes, it will call the OnPanic callback. If the watcher process encounters an error or dies, then appropriate callback is called if configured.

Types

type Config

type Config struct {
	// BufferSize specifies the size of the read buffer between dup-ed stderr and the real one. Optional/
	BufferSize int
	// PanicDetectorBufferSize specifies the size of the buffer used to detect panic.
	// Too low value will cause the detection to fail. Optional.
	PanicDetectorBufferSize int
	// OnPanic is a callback that will be called after your application dies, if a panic is detected. Required.
	OnPanic func(Panic)
	// OnWatcherErr is a callback that will be called when watcher process encounters an error. Optional.
	OnWatcherError func(error)
	// OnWatcherDied is a callback that will be called when watcher process dies.
	// It is recommended to set this callback to shut down your application gracefully. Optional.
	OnWatcherDied func(error)
}

Config holds the configuration of panicwatch.

type Panic

type Panic struct {
	Type    PanicType
	Message string
	Stack   string
}

Panic holds information about a panic parsed from stderr of your application.

func (Panic) AsError

func (p Panic) AsError() error

AsError returns the Panic as an instance of error interface. When the panic message and stack aren't malformed, it will return *goerrors.Error, otherwise it will fall back to a simple *errors.errorString, containing just the message.

type PanicType

type PanicType string

const (
	TypePanic      PanicType = "panic"
	TypeFatalError PanicType = "fatal error"
)