monitor

package
Version: v0.1.34 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 29, 2022 License: MIT Imports: 12 Imported by: 1

Documentation

Overview

Package monitor simplifies retrieval of log messages.

The minimum interface is Connection below. Some implementations of Connection might be able to offload the task of filtering results to the underlying storage engine, which has the potential to be much more efficient. A number of optional interfaces -- listed below -- are available and will be used by if appropriate.

The optional interfaces that can be exploited for filtering are:

type IsLogNamer interface {
    IsLogName(name string) (bool, error)
}

type LogNamesWithSubstringer interface {
    LogNamesWithSubstring(match string) ([]string, bool)
}

type LogNamesWithRegexper interface {
    LogNamesWithRegexp(expr string) ([]string, bool)
}

type LogNamesWithMatcheser interface {
	LogNamesWithMatches(NameMatches) ([]string, error)
}

type StreamWithFilterer interface {
    StreamWithFilter(ctx context.Context, name string,
      start *Time, finish *Time, filter FilterFunc) (Iterator, error)
}

type StreamWithMessageSubstringer interface {
    StreamWithMessageSubstring(ctx context.Context, name string,
      start *Time, finish *Time, match string) (Iterator, error)
}

type StreamWithMessageRegexper interface {
    StreamWithMessageRegexp(ctx context.Context, name string,
      start *Time, finish *Time, expr string) (Iterator, error)
}

type StreamWithIdentifierSubstringer interface {
    StreamWithIdentifierSubstring(ctx context.Context, name string,
      start *Time, finish *Time, match string) (Iterator, error)
}

type StreamWithIdentifierRegexper interface {
    StreamWithIdentifierRegexp(ctx context.Context, name string,
      start *Time, finish *Time, expr string) (Iterator, error)
}

type StreamWithMatcheser interface {
    StreamWithMatches(ctx context.Context, name string,
      start *Time, finish *Time, cond Matches) (Iterator, error)
}

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrIterationFinished = errors.New("attempting to Scan after iteration has ended")
	ErrNextNotCalled     = errors.New("attempting to Scan before a successful call to Next or NextContext")
)

Common iteration errors.

Functions

func IsLogName

func IsLogName(ctx context.Context, c Connection, name string) (bool, error)

IsLogName returns true iff the given string is a log name of the given Connection c.

func LogNamesWithMatches

func LogNamesWithMatches(ctx context.Context, c Connection, cond NameMatches) ([]string, error)

LogNamesWithMatches is the same as LogNames, with the exception that log names are filtered against the conditions 'cond'.

func LogNamesWithRegexp

func LogNamesWithRegexp(ctx context.Context, c Connection, expr string) ([]string, error)

LogNamesWithRegexp is the same as LogNames, with the exception that log names are filtered for those matching the given regular expression.

func LogNamesWithSubstring

func LogNamesWithSubstring(ctx context.Context, c Connection, match string) ([]string, error)

LogNamesWithSubstring is the same as LogNames, with the exception that log names are filtered for those containing the substring 'match'.

func ParseTime

func ParseTime(s string, roundUp bool, loc *time.Location) (bool, time.Time)

ParseTime attempts to parse s to a time.Time. Valid possibilities for s are:

  "now"       - the current time;
  "today"     - today;
  "tomorrow"  - tomorrow;
  "yesterday" - yesterday;
  "noon", "midday" - noon;
  "midnight"  - midnight;
  day of the week - a day of the week ("Monday"/"Mon", "Tuesday"/"Tue",
                "Wednesday"/"Wed" etc.), which will be interpreted as the
                most recent occurrence of that day;
  month       - a month ("January"/"Jan", "February"/"Feb" etc.), which
                will be interpreted as the most recent occurrence of that
                month;
  a timestamp - valid formats include "3:04PM", "15:04", "15:04:05",
                "Jan _2 15:04", "Jan _2 15:04:05", "Jan _2 15:04:05.000",
				   and "2006-01-02 15:04:05".

The value of rounding will determine whether the time will be rounded up (towards the end of the day, indicated by 'roundUp' equal to true) or down (towards the start of the day, indicated by 'roundUp' equal to false) when insufficient resolution is given.

func Scan

func Scan(dst *Entry, src Entry)

Scan copies the contents of the Entry src into dest. Any previously set data in dest will be deleted or overwritten.

Types

type BufferedIterator

type BufferedIterator interface {
	Iterator
	// Buffered returns true iff the next call to Next or NextContext is
	// guaranteed not to block.
	Buffered() bool
}

BufferedIterator described an Iterator with buffer.

func NewBufferedIterator

func NewBufferedIterator(itr Iterator, bufSize int) BufferedIterator

NewBufferedIterator returns an iterator wrapping 'itr' that buffers the entries. Calling Close on the returned iterator will Close the wrapped iterator 'itr'.

type Connection

type Connection interface {
	// LogNames returns the log names.
	LogNames(ctx context.Context) ([]string, error)
	// Stream returns an iterator down which entries from the log 'name' are
	// passed. Only entries falling into the range determined by start and
	// finish will be returned. If start is unassigned then the start of the
	// log will be used; if end is unassigned then no end is used. The
	// caller should ensure that the returned Iterator is closed, otherwise
	// a resource leak will result.
	Stream(ctx context.Context, name string, start *Time, finish *Time) (Iterator, error)
}

Connection is the interface satisfied by a connection to a log.

type Entry

type Entry struct {
	T   time.Time      `json:"timestamp,omitempty"` // The timestamp
	Msg logger.Message `json:"message,omitempty"`   // The log message
}

Entry represents an entry in a log.

func (Entry) String

func (e Entry) String() string

String returns a string description of the Entry.

type FilterFunc

type FilterFunc func(Entry) bool

FilterFunc can be used to filter an entry. The filter function should return true iff the entry is to be kept.

A nil-valued filter function should be interpreted as the absence of a filter, and hence is equivalent to a filter function that always returns true.

func And

func And(f ...FilterFunc) FilterFunc

And returns the filter function corresponding to f_1 && f_2 && ... && f_n, where the f_i are the given arguments. As with &&, And will short-circuit evaluation if one of the f_i returns false.

func Or

func Or(f ...FilterFunc) FilterFunc

Or returns the filter function corresponding to f_1 || f_2 || ... || f_n, where the f_i are the given arguments. As with ||, Or will short-circuit evaluation if one of the f_i returns true.

type Iterator

type Iterator interface {
	// Close closes the iterator, preventing further iteration.
	Close() error
	// Err returns the last error, if any, encountered during iteration. Err
	// may be called after Close.
	Err() error
	// Next advances the iterator. Returns true on successful advance of the
	// iterator; false otherwise. Next or NextContext must be called before the
	// first call to Scan.
	Next() bool
	// NextContext advances the iterator. Returns true on successful advance of
	// the iterator; false otherwise. Next or NextContext must be called before
	// the first call to Scan.
	NextContext(ctx context.Context) (bool, error)
	// Scan copies the current Entry into "dest". Any previously set data in
	// "dest" will be deleted or overwritten.
	Scan(dest *Entry) error
}

Iterator describes an Entry iterator.

func EmptyIterator

func EmptyIterator() Iterator

EmptyIterator returns an iterator with no entries.

func FilterIterator

func FilterIterator(itr Iterator, filter FilterFunc) Iterator

FilterIterator wraps the given Iterator, filtering the entries using the given FilterFunc. Calling Close on the returned iterator will Close the wrapped iterator 'itr'.

func SliceIterator

func SliceIterator(S []Entry) Iterator

SliceIterator returns an iterator for the given slice.

func StreamWithFilter

func StreamWithFilter(ctx context.Context, c Connection, name string, start *Time, finish *Time, filter FilterFunc) (Iterator, error)

StreamWithFilter is the same as Stream, with the exception that entries are filtered via a user-provided filter function. The caller should ensure that the returned Iterator is closed, otherwise a resource leak will result.

func StreamWithIdentifierRegexp

func StreamWithIdentifierRegexp(ctx context.Context, c Connection, name string, start *Time, finish *Time, expr string) (Iterator, error)

StreamWithIdentifierRegexp is the same as Stream, with the exception that entries are filtered for those whose message identifier matches the given regular expression. This is functionally equivalent to calling StreamWithFilter using the filter function:

re := regexp.MustCompile(expr)
func(e Entry) bool {
    return re.MatchString(e.Msg.Identifier)
}

Some implementations of Connection might be able to offload the task of filtering to the underlying storage engine, hence this has the potential to be much more efficient than the corresponding call to StreamWithFilter.

func StreamWithIdentifierSubstring

func StreamWithIdentifierSubstring(ctx context.Context, c Connection, name string, start *Time, finish *Time, match string) (Iterator, error)

StreamWithIdentifierSubstring is the same as Stream, with the exception that entries are filtered for those whose message identifier contains the substring 'match'. This is functionally equivalent to calling StreamWithFilter using the filter function:

func(e Entry) bool {
    return strings.Contains(e.Msg.Identifier, match)
}

Some implementations of Connection might be able to offload the task of filtering to the underlying storage engine, hence this has the potential to be much more efficient than the corresponding call to StreamWithFilter.

func StreamWithMatches

func StreamWithMatches(ctx context.Context, c Connection, name string, start *Time, finish *Time, cond Matches) (Iterator, error)

StreamWithMatches is the same as Stream, with the exception that entries are filtered against the conditions 'cond'.

Some implementations of Connection might be able to offload the task of filtering to the underlying storage engine, hence this has the potential to be much more efficient than the corresponding call to StreamWithFilter.

func StreamWithMessageRegexp

func StreamWithMessageRegexp(ctx context.Context, c Connection, name string, start *Time, finish *Time, expr string) (Iterator, error)

StreamWithMessageRegexp is the same as Stream, with the exception that entries are filtered for those whose message content matches the given regular expression. This is functionally equivalent to calling StreamWithFilter using the filter function:

re := regexp.MustCompile(expr)
func(e Entry) bool {
    return re.MatchString(e.Msg.Message)
}

Some implementations of Connection might be able to offload the task of filtering to the underlying storage engine, hence this has the potential to be much more efficient than the corresponding call to StreamWithFilter.

func StreamWithMessageSubstring

func StreamWithMessageSubstring(ctx context.Context, c Connection, name string, start *Time, finish *Time, match string) (Iterator, error)

StreamWithMessageSubstring is the same as Stream, with the exception that entries are filtered for those whose message content contains the substring 'match'. This is functionally equivalent to calling StreamWithFilter using the filter function:

func(e Entry) bool {
    return strings.Contains(e.Msg.Message, match)
}

Some implementations of Connection might be able to offload the task of filtering to the underlying storage engine, hence this has the potential to be much more efficient than the corresponding call to StreamWithFilter.

type Matches

type Matches struct {
	MessageSubstring       string `json:",omitempty"` // A substring all messages must contain
	MessageNotSubstring    string `json:",omitempty"` // A substring all messages must not contain
	MessageRegexp          string `json:",omitempty"` // A regular expression all messages must match
	MessageNotRegexp       string `json:",omitempty"` // A regular expression all messages must not match
	IdentifierSubstring    string `json:",omitempty"` // A substring all identifiers must contain
	IdentifierNotSubstring string `json:",omitempty"` // A substring all identifiers must not contain
	IdentifierRegexp       string `json:",omitempty"` // A regular expression all identifiers must match
	IdentifierNotRegexp    string `json:",omitempty"` // A regular expression all identifiers must not match
}

Matches provides a way to filter for specific entries. Empty values will be interpreted as meaning no condition, so will be ignored.

func (Matches) String

func (c Matches) String() string

String returns a string description of the matches.

type NameMatches

type NameMatches struct {
	Substring    string `json:",omitempty"` // A substring all log names must contain
	NotSubstring string `json:",omitempty"` // A substring all log names must not contain
	Regexp       string `json:",omitempty"` // A regular expression all log names must match
	NotRegexp    string `json:",omitempty"` // A regular expression all log names must not match
}

NameMatches provides a way to filter for specific log names. Empty values will be interpreted as meaning no condition, so will be ignored.

func (NameMatches) String

func (c NameMatches) String() string

String returns a string description of the matches.

type Time

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

Time represents a point in time, which can be either unassigned, a time, or as an offset from the most recent entry in the log. A positive offset represents an offset into the past; a negative offset represents an offset into the future.

func NewOffset

func NewOffset(n int64) *Time

NewOffset return a new offset set to n.

func NewTime

func NewTime(t time.Time) *Time

NewTime returns a new time set to t.

func ParseEndTime

func ParseEndTime(s string, loc *time.Location) (bool, *Time)

ParseEndTime attempts to parse s, interpreted as an end time, and return a *Time. Valid possibilities for s are as in ParseTime, along with:

"never", "none" - an unassigned time;
"end", "finish" - the last entry in the log, represented by an
              offset of 0;
a duration  - the current time subtract the duration;
an integer  - an offset by this value.

func ParseStartTime

func ParseStartTime(s string, loc *time.Location) (bool, *Time)

ParseStartTime attempts to parse s, interpreted as a start time, and return a *Time. Valid possibilities for s are as in ParseTime, along with:

"start", "beginning" - the start of the log, represented by an
              unassigned time;
a duration  - the current time subtract the duration;
an integer  - an offset by this value.

func (*Time) After

func (t *Time) After(s *Time) bool

After returns true iff both t and s are assigned, and one of the following two conditions is satisfied: - both t and s represent times, with tTime.After(sTime); - both t and s represent offsets, with tOffset < sOffset.

func (*Time) Before

func (t *Time) Before(s *Time) bool

Before returns true iff both t and s are assigned, and one of the following two conditions is satisfied: - both t and s represent times, with tTime < sTime; - both t and s represent offsets, with tOffset > sOffset.

func (*Time) Equal

func (t *Time) Equal(s *Time) bool

Equal returns true iff both t and s are assigned, and one of the following two conditions is satisfied: - both t and s represent times, with tTime == sTime; - both t and s represent offsets, with tOffset == sOffset.

func (*Time) GobDecode

func (t *Time) GobDecode(b []byte) error

GobDecode attempts to gob-decode the given bytes into t.

func (*Time) GobEncode

func (t *Time) GobEncode() ([]byte, error)

GobEncode gob-encodes t.

func (*Time) IsAssigned

func (t *Time) IsAssigned() bool

IsAssigned returns true iff t has a value assigned (equivalently, if either IsOffset or IsTime returns true).

func (*Time) IsOffset

func (t *Time) IsOffset() (bool, int64)

IsOffset returns true iff t is equal to an offset. If true, also returns the offset amount.

func (*Time) IsTime

func (t *Time) IsTime() (bool, time.Time)

IsTime returns true iff t is equal to a time. If true, also returns the time.

func (*Time) IsUnassigned

func (t *Time) IsUnassigned() bool

IsUnassigned returns true iff t does not have a value assigned (equivalently, if both IsOffset and IsTime return false).

func (*Time) MarshalJSON

func (t *Time) MarshalJSON() ([]byte, error)

MarshalJSON marshals t into JSON.

func (*Time) String

func (t *Time) String() string

String returns a string representation of t.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) error

UnmarshalJSON attempts to unmarshal the given JSON into t.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL