sutureslog

README

sutureslog

go get github.com/thejerf/sutureslog

sutureslog is an adjunct to the suture package. It is isolate because sutureslog naturally needs a Go with slog in it, but I do not want to impose that requirement on the suture library itself and break backwards compatibility.

Documentation is available in the godoc, and as for the rest of what suture is, see the github link to it in the previous paragraph.

Documentation

Overview

Package sutureslog implements a slog-based handler for suture events.

Note this is a separate module from suture to avoid forcing suture itself to require a Go version that has log/slog. That dependency is isolated to just this module. That means you must run a separate

go get github.com/thejerf/suture/sutureslog

Passing this as a logger for a Supervisor looks like:

// have some *slog.Logger called logger
supervisor := suture.New(
    "my supervisor name",
    suture.Spec{
        EventHook: sutureslog.Handler{Logger: logger}.MustHook(),
    },
)

Index

• Constants
• Variables
• type Handler
  • func (h *Handler) Hook() (func(suture.Event), error)
  • func (h *Handler) MustHook() func(suture.Event)

Constants

const (
	// LogStopTimeout is logged for suture.EventBackoff.
	LogStopTimeout = "stopping service has timed out"

	// LogResume is logged for suture.EventResume
	LogResume = "supervisor has resumed restarting services"

	// LogBackoff is logged for suture.EventBackoff
	LogBackoff = "supervisor has entered backoff state"

	// LogServicePanic is logged for suture.EventServicePanic
	LogServicePanic = "service under supervision has panicked"

	// LogServiceTerminate is logged for
	// suture.EventServiceTerminate
	LogServiceTerminate = "service has terminated by returning"
)

Variables

var ErrNoHandlerSpecified = errors.New("no slog handler specified")

Types

type Handler

type Handler struct {
	StopTimeoutLevel      slog.Leveler
	ServicePanicLevel     slog.Leveler
	ServiceTerminateLevel slog.Leveler
	BackoffLevel          slog.Leveler
	ResumeLevel           slog.Leveler

	Logger *slog.Logger
}

A Handler handles incoming events and manages logging them to slog.

Once a Supervisor starts running with a Hook from this handler, the values must not be changed.

If the slog.Leveler is left nil, a default level will be used. A minimal definition includes only a Handler.

For EventStopTimeout and EventServicePanic, this default level will be slog.LevelError.

For EventServiceTerminate, the default level is slog.LevelInfo.

For the rest it will be slog.LevelDebug.

For Services passed as logging values, if the service implements slog.LogValuer, that will be passed to slog. Otherwise, if it implements fmt.Stringer, it will be stringified using that. Otherwise, it will be passed as an Any value.

The log messages that will be emitted by each event correspond to the constants defined by this package; this can be used by something like github.com/thejerf/slogassert to validate proper functioning of your code. See sutureslog_test.go in this package for examples.

func (*Handler) Hook

func (h *Handler) Hook() (func(suture.Event), error)

Hook returns an event hook suitable for passing into a suture.Spec.

The only possible error is ErrNoHandlerSpecified. If you statically guarantee that can't happen you can elide this error.

func (*Handler) MustHook

func (h *Handler) MustHook() func(suture.Event)

MustHook will return a valid event hook function or panic.