journal

Documentation

Index

• Constants
• Variables
• type DisabledEvents
  • func EnvDisabledEvents() DisabledEvents
  • func ParseDisabledEvents(s string) (DisabledEvents, error)
• type Event
• type EventType
  • func (et EventType) Enabled() bool
  • func (et EventType) String() string
• type EventTypeRegistry
  • func NewEventTypeRegistry(disabled DisabledEvents) EventTypeRegistry
• type Journal
  • func NilJournal() Journal
  • func OpenFSJournal(lr repo.Repo, disabled DisabledEvents) (Journal, error)

Constants

const RFC3339nocolon = "2006-01-02T150405Z0700"

Variables

var DefaultDisabledEvents = DisabledEvents{
	EventType{System: "mpool", Event: "add"},
	EventType{System: "mpool", Event: "remove"},
}

DefaultDisabledEvents lists the journal events disabled by default, usually because they are considered noisy.

Types

type DisabledEvents

type DisabledEvents []EventType

DisabledEvents is the set of event types whose journaling is suppressed.

func EnvDisabledEvents

func EnvDisabledEvents() DisabledEvents

func ParseDisabledEvents

func ParseDisabledEvents(s string) (DisabledEvents, error)

ParseDisabledEvents parses a string of the form: "system1:event1,system1:event2[,...]" into a DisabledEvents object, returning an error if the string failed to parse.

It sanitizes strings via strings.TrimSpace.

type Event

type Event struct {
	EventType

	Timestamp time.Time
	Data      interface{}
}

Event represents a journal entry.

See godocs on Journal for more information.

type EventType

type EventType struct {
	System string
	Event  string
	// contains filtered or unexported fields
}

EventType represents the signature of an event.

func (EventType) Enabled

func (et EventType) Enabled() bool

Enabled returns whether this event type is enabled in the journaling subsystem. Users are advised to check this before actually attempting to add a journal entry, as it helps bypass object construction for events that would be discarded anyway.

All event types are enabled by default, and specific event types can only be disabled at Journal construction time.

func (EventType) String

func (et EventType) String() string

type EventTypeRegistry

type EventTypeRegistry interface {
	// RegisterEventType introduces a new event type to a journal, and
	// returns an EventType token that components can later use to check whether
	// journalling for that type is enabled/suppressed, and to tag journal
	// entries appropriately.
	RegisterEventType(system, event string) EventType
}

EventTypeRegistry is a component that constructs tracked EventType tokens, for usage with a Journal.

func NewEventTypeRegistry

func NewEventTypeRegistry(disabled DisabledEvents) EventTypeRegistry

type Journal

type Journal interface {
	EventTypeRegistry

	// RecordEvent records this event to the journal, if and only if the
	// EventType is enabled. If so, it calls the supplier function to obtain
	// the payload to record.
	//
	// Implementations MUST recover from panics raised by the supplier function.
	RecordEvent(evtType EventType, supplier func() interface{})

	// Close closes this journal for further writing.
	Close() error
}

Journal represents an audit trail of system actions.

Every entry is tagged with a timestamp, a system name, and an event name. The supplied data can be any type, as long as it is JSON serializable, including structs, map[string]interface{}, or primitive types.

For cleanliness and type safety, we recommend to use typed events. See the *Evt struct types in this package for more info.

func NilJournal

func NilJournal() Journal

func OpenFSJournal

func OpenFSJournal(lr repo.Repo, disabled DisabledEvents) (Journal, error)

OpenFSJournal constructs a rolling filesystem journal, with a default per-file size limit of 1GiB.