eventlog

Documentation

Overview

Package eventlog defines a reverse time-ordered log of events over a sliding window of time before the most recent item in the log.

New items are added to the head of the log (the newest end), and items that fall outside the designated window are pruned from its tail (the oldest). Items within the log are indexed by lexicographically-ordered cursors.

Index

• Constants
• Variables
• func FindType(events []abci.Event) (string, bool)
• type ABCIEventer
• type Info
• type Item
• type Log
  • func New(opts LogSettings) (*Log, error)
  • func (lg *Log) Add(etype string, data types.EventData) error
  • func (lg *Log) Info() Info
  • func (lg *Log) Scan(f func(*Item) error) (Info, error)
  • func (lg *Log) WaitScan(ctx context.Context, c cursor.Cursor, f func(*Item) error) (Info, error)
• type LogSettings
• type Metrics
  • func NopMetrics() *Metrics
  • func PrometheusMetrics(namespace string, labelsAndValues ...string) *Metrics

Constants

const MetricsSubsystem = "eventlog"

Variables

var ErrLogPruned = errors.New("log pruned")

ErrLogPruned is returned by Add to signal that at least some events within the time window were discarded by pruning in excess of the size limit. This error may be wrapped, use errors.Is to test for it.

var ErrStopScan = errors.New("stop scanning")

ErrStopScan is returned by a Scan callback to signal that scanning should be terminated without error.

Functions

func FindType

func FindType(events []abci.Event) (string, bool)

FindType reports whether events contains a tm.event event, and if so returns its value, which is the type of the underlying event item.

Types

type ABCIEventer

type ABCIEventer interface {
	// Return any ABCI events metadata the receiver contains.
	// The reported slice must not contain a type (tm.event) record, since some
	// events share the same structure among different event types.
	ABCIEvents() []abci.Event
}

ABCIEventer is an optional extension interface that may be implemented by event data types, to expose ABCI metadata to the event log. If an event item does not implement this interface, it is presumed to have no ABCI metadata.

type Info

type Info struct {
	Oldest cursor.Cursor // the cursor of the oldest item in the log
	Newest cursor.Cursor // the cursor of the newest item in the log
	Size   int           // the number of items in the log
}

Info records the current state of the log at the time of a scan operation.

type Item

type Item struct {
	Cursor cursor.Cursor
	Type   string
	Data   types.EventData
	Events []abci.Event
}

An Item is a single event item.

type Log

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

A Log is a reverse time-ordered log of events in a sliding window of time before the newest item. Use Add to add new items to the front (head) of the log, and Scan or WaitScan to traverse the current contents of the log.

After construction, a *Log is safe for concurrent access by one writer and any number of readers.

func New

func New(opts LogSettings) (*Log, error)

New constructs a new empty log with the given settings.

func (*Log) Add

func (lg *Log) Add(etype string, data types.EventData) error

Add adds a new item to the front of the log. If necessary, the log is pruned to fit its constraints on size and age. Add blocks until both steps are done.

Any error reported by Add arises from pruning; the new item was added to the log regardless whether an error occurs.

func (*Log) Info

func (lg *Log) Info() Info

Info returns the current state of the log.

func (*Log) Scan

func (lg *Log) Scan(f func(*Item) error) (Info, error)

Scan scans the current contents of the log, calling f with each item until all items are visited or f reports an error. If f returns ErrStopScan, Scan returns nil, otherwise it returns the error reported by f.

The Info value returned is valid even if Scan reports an error.

func (*Log) WaitScan

func (lg *Log) WaitScan(ctx context.Context, c cursor.Cursor, f func(*Item) error) (Info, error)

WaitScan blocks until the cursor of the frontmost log item is different from c, then executes a Scan on the contents of the log. If ctx ends before the head is updated, WaitScan returns an error without calling f.

The Info value returned is valid even if WaitScan reports an error.

type LogSettings

type LogSettings struct {
	// The size of the time window measured in time before the newest item.
	// This value must be positive.
	WindowSize time.Duration

	// The maximum number of items that will be retained in memory within the
	// designated time window. A value ≤ 0 imposes no limit, otherwise items in
	// excess of this number will be dropped from the log.
	MaxItems int

	// The cursor source to use for log entries. If not set, use wallclock time.
	Source cursor.Source

	// If non-nil, exported metrics to update. If nil, metrics are discarded.
	Metrics *Metrics
}

LogSettings configure the construction of an event log.

type Metrics

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

Metrics define the metrics exported by the eventlog package.

func NopMetrics

func NopMetrics() *Metrics

func PrometheusMetrics

func PrometheusMetrics(namespace string, labelsAndValues ...string) *Metrics