events: git.wegmueller.it/illumos/events Index | Files | Directories

package events

import "git.wegmueller.it/illumos/events"

Index

Package Files

event.go event_unsafe.go handler.go logger.go signal.go source.go source_go17.go terminal.go terminal_linux.go

Variables

var DefaultLogger = NewLogger(nil)

DefaultLogger is the default logger used by the Log function. This may be overwritten by the program to change the default route for log events.

func Debug Uses

func Debug(format string, args ...interface{})

Debug emits a debug event to the default logger.

func IsInterruption Uses

func IsInterruption(err error) bool

IsInterruption returns true if the given error was caused by receiving an interruption signal.

func IsSignal Uses

func IsSignal(err error, signals ...os.Signal) bool

IsSignal returns true if the given error is a *SignalError that was generated upon receipt of one of the given signals. If no signal is passed, the function only tests for err to be of type *SginalError.

func IsTerminal Uses

func IsTerminal(fd int) bool

IsTerminal returns true if the given file descriptor is a terminal.

func IsTermination Uses

func IsTermination(err error) bool

IsTermination returns true if the given error was caused by receiving a termination signal.

func Log Uses

func Log(format string, args ...interface{})

Log emits a log event to the default logger.

func Signal Uses

func Signal(sigchan <-chan os.Signal) <-chan os.Signal

Signal triggers events on the default handler for every signal that arrives on sigchan. The function returns a channel on which signals are forwarded, the program should use this channel instead of sigchan to receive signals.

func SignalWith Uses

func SignalWith(handler Handler, sigchan <-chan os.Signal) <-chan os.Signal

SignalWith triggers events on handler for every signal that arrives on sigchan. The function returns a channel on which signals are forwarded, the program should use this channel instead of sigchan to receive signals.

func SortArgs Uses

func SortArgs(args Args)

SortArgs sorts a list of argument by their argument names.

This is not a stable sorting operation, elements with equal values may not be in the same order they were originally after the function returns.

func SourceForPC Uses

func SourceForPC(pc uintptr) (file string, line int)

SourceForPC returns the file and line given a program counter address. The file path is in the canonical form for Go programs, starting with the package path.

func WithSignals Uses

func WithSignals(ctx context.Context, signals ...os.Signal) (context.Context, context.CancelFunc)

WithSignals returns a copy of the given context which may be canceled if any of the given signals is received by the program.

type Arg Uses

type Arg struct {
    Name  string
    Value interface{}
}

Arg represents a single event argument.

type Args Uses

type Args []Arg

Args reprsents a list of event arguments.

func A Uses

func A(m map[string]interface{}) Args

A constructs an argument list from a map.

func (Args) Get Uses

func (args Args) Get(name string) (v interface{}, ok bool)

Get returns the value of the argument with name within args.

func (Args) Map Uses

func (args Args) Map() map[string]interface{}

Map converts an argument list to a map representation. In cases where the list contains multiple arguments with the same name the value of the last one will be seen in the map.

type Event Uses

type Event struct {
    // Message carries information about the event in a human-readable format.
    Message string

    // Source represents the location where this event was generated from.
    Source string

    // Args is the list of arguments of the event, it is intended to give
    // context about the information carried by the even in a format that can
    // be processed by a program.
    Args Args

    // Time is the time at which the event was generated.
    Time time.Time

    // Debug is set to true if this is a debugging event.
    Debug bool
}

The Event type represents unique events generated by the program. They carry context about how they were triggered and information to pass to handlers.

func (*Event) Clone Uses

func (e *Event) Clone() *Event

Clone makes a deep copy of the event, the returned value doesn't shared any pointer with the original.

type Handler Uses

type Handler interface {
    // HandleEvent is called by event producers on their event handler, passing
    // one event object as argument to the function.
    //
    // The handler MUST NOT retain any references to the event or its fields. If
    // the handler needs to capture the event is has to create a copy by calling
    // e.Clone.
    HandleEvent(e *Event)
}

The Handler interface is implemented by types that intend to be event routers or apply transformations to an event before forwarding it to another handler.

var (
    // Discard is a handler that does nothing with the events it receives.
    Discard Handler = HandlerFunc(func(e *Event) {})

    // DefaultHandler is the default handler used when non is specified.
    DefaultHandler Handler = Discard
)

func MultiHandler Uses

func MultiHandler(handlers ...Handler) Handler

MultiHandler returns a new Handler which broadcasts the events it receives to its list of handlers.

type HandlerFunc Uses

type HandlerFunc func(*Event)

HandlerFunc makes it possible for simple function types to be used as event handlers.

func (HandlerFunc) HandleEvent Uses

func (f HandlerFunc) HandleEvent(e *Event)

HandleEvent calls f.

type Logger Uses

type Logger struct {
    // Handler is the event handler receiving events from the logger.
    Handler Handler

    // Args is a list of arguments that get automatically injected into every
    // events produced by the logger.
    Args Args

    // CallDepth is used to adjust which caller the logger should report its
    // events are coming from.
    // Leaving to zero means reporting the direct caller of the logger's
    // methods.
    CallDepth int

    // EnableSource controls whether the logger should report the program counter
    // address of its caller on the events it produces.
    // This has a significant impact on the performance of the logger's Log and
    // Debug method but also provides very important insights, be mindful about
    // turning it on or off.
    EnableSource bool

    // EnableDebug controls whether calls to Debug produces events.
    EnableDebug bool
}

A Logger is a wrapper around an event handler which exposes a Log method for formatting event messages before sending them to the handler.

The format supported by the Log method is a superset of the fmt-style format, where the 'verbs' may include a column-surrounded value representing the name of the matching argument.

The Log method also makes a special case when it gets an events.Args as last argument, it doesn't use it to format the message and instead simply append it to the event's argument list.

Here's an example with the defalut logger:

events.Log("Hello %{name}s!", "Luke", events.Args{
	{"from", "Han"},
})

Which produces an event that looks like this:

events.Event{
	Message: "Hello Luke!",
	Args:    events.Args{{"name", "Luke"}, {"from", "Han"}},
	...
}

Logger instances are safe to use concurrently from multiple goroutines.

func NewLogger Uses

func NewLogger(handler Handler) *Logger

NewLogger allocates and returns a new logger which sends events to handler.

func (*Logger) Debug Uses

func (l *Logger) Debug(format string, args ...interface{})

Debug is like Log but only produces events if the logger has debugging enabled.

func (*Logger) Log Uses

func (l *Logger) Log(format string, args ...interface{})

Log formats an event and sends it to the logger's handler.

func (*Logger) With Uses

func (l *Logger) With(args Args) *Logger

With returns a new Logger which is a copy of l augmented with args.

type SignalError Uses

type SignalError struct {
    os.Signal
}

SignalError is a wrapper for the os.Signal type which also implements the error interface so it can be reported by the Err method of a context.

func (*SignalError) Error Uses

func (s *SignalError) Error() string

Error satisfies the error interface.

Directories

PathSynopsis
ecslogsPackage ecslogs provides the implementation of an event handler that outputs events in a ecslogs-compatible format.
eventstest
httpevents
logPackage log provides the implementation of a shim between the standard log package and event handlers.
netevents
sigeventsPackage sigevents installs signal handlers for SIGUSR1 and SIGUSR2, enabling debug logs when the former is received, or disabling them on the latter.
textPackage text provides the implementation of an event handler that outputs events in a human-readable format.

Package events imports 14 packages (graph) and is imported by 7 packages. Updated 2019-01-30. Refresh now. Tools for package owners.