buildlog

Documentation

Overview

Package buildlog implements a logging system for build operations. Various parts of the API use Handler's to export logging information.

Index

• Variables
• func LogWriter(lh Handler, stream Stream) io.WriteCloser
• func ReadJSONStream(dst Handler, src io.Reader) error
• func ReadLog(lh Handler, stream Stream, r io.Reader) error
• func ValidateName(name string) error
• type DirLogger
  • func (d DirLogger) NewLog(name string) (Handler, error)
  • func (d DirLogger) ReadLog(name string, h Handler) (err error)
• type Handler
  • func InterceptMeta(h Handler, callback func(string)) Handler
  • func MultiLogHandler(handlers ...Handler) Handler
  • func MutexedLogHandler(handler Handler) Handler
  • func NewJSONHandler(w io.WriteCloser) (Handler, error)
  • func StdLogHandler(l *log.Logger) Handler
• type IllegalRuneError
  • func (e IllegalRuneError) Error() string
• type Line
  • func (ll Line) String() string
• type LogReader
• type LogStore
• type Logger
  • func TextLogger(w io.Writer) Logger
• type Stream
  • func ParseStream(name string) (Stream, error)
  • func (s Stream) String() string
  • func (s Stream) Valid() bool

Variables

var DefaultHandler = StdLogHandler(log.New(os.Stderr, "", log.LstdFlags))

DefaultHandler is the default Handler. It logs to stderr.

var ErrInvalidStream = errors.New("invalid stream")

ErrInvalidStream is an error indicating that the stream is not valid.

Functions

func LogWriter

func LogWriter(lh Handler, stream Stream) io.WriteCloser

LogWriter returns an io.WriteCloser that is logged. The Handler must be mutexed if it is also used by anything else. Spawns a goroutine.

func ReadJSONStream

func ReadJSONStream(dst Handler, src io.Reader) error

ReadJSONStream reads a log from a JSON array.

func ReadLog

func ReadLog(lh Handler, stream Stream, r io.Reader) error

ReadLog reads a log from a reader. The log is put to the Handler on the specified stream.

func ValidateName

func ValidateName(name string) error

ValidateName validates a name which must only contain [a-z] or [_- ].

Types

type DirLogger

type DirLogger struct {
	Dir string
}

DirLogger is a LogStore implementation which stores JSON logs in a directory.

func (DirLogger) NewLog

func (d DirLogger) NewLog(name string) (Handler, error)

NewLog returns a handler for a new log, implementing the Logger interface.

func (DirLogger) ReadLog

func (d DirLogger) ReadLog(name string, h Handler) (err error)

ReadLog reads a log into the Handler.

type Handler

type Handler interface {
	Log(Line) error
	io.Closer
}

Handler is an interface used for log output.

func InterceptMeta

func InterceptMeta(h Handler, callback func(string)) Handler

InterceptMeta returrns a Handler which executes a callback instead of logging messages in StreamMeta.

func MultiLogHandler

func MultiLogHandler(handlers ...Handler) Handler

MultiLogHandler returns a Handler that logs to all given handlers.

func MutexedLogHandler

func MutexedLogHandler(handler Handler) Handler

MutexedLogHandler returns a Handler which is thread-safe.

func NewJSONHandler

func NewJSONHandler(w io.WriteCloser) (Handler, error)

NewJSONHandler returns a new Handler which writes a log as JSON to the given writer. If an error occured, the writer may or may not be closed.

func StdLogHandler

func StdLogHandler(l *log.Logger) Handler

StdLogHandler creates a Handler which wraps a go stdlib logger. For this logger, Close is a no-op.

type IllegalRuneError

type IllegalRuneError struct {
	// Rune is the illegal rune.
	Rune rune

	// Pos is the index of the rune (by rune - not by byte).
	Pos int

	// Strign is the original string containing the invalid rune.
	String string
}

IllegalRuneError is an error type for when an invalid rune is found.

func (IllegalRuneError) Error

func (e IllegalRuneError) Error() string

type Line

type Line struct {
	// Text is the text of the log line.
	Text string `json:"text"`

	// Stream is the stream over which the log line was recieved.
	Stream Stream `json:"stream"`
}

Line is a line of log output.

func (Line) String

func (ll Line) String() string

type LogReader

type LogReader interface {
	// ReadLog reads a log into the Handler.
	// The name be valid according to ValidateName.
	ReadLog(name string, h Handler) error
}

LogReader is a generic log-reading interface.

type LogStore

type LogStore interface {
	Logger
	LogReader
}

LogStore is an interface for saving and reading logs.

type Logger

type Logger interface {
	// NewLog returns a Handler to write a new log.
	// The name be valid according to ValidateName.
	NewLog(name string) (Handler, error)
}

Logger is a generic logging service.

func TextLogger

func TextLogger(w io.Writer) Logger

TextLogger returns a Logger that logs to the given io.Writer in human-readable format.

type Stream

type Stream uint8

Stream is a stream which Lines can be tagged with.

const (
	// StreamStdout is a LogStream for stdout.
	StreamStdout Stream = 1

	// StreamStderr is a LogStream for stderr.
	StreamStderr Stream = 2

	// StreamBuild is a LogStream for info from the build system.
	StreamBuild Stream = 3

	// StreamMeta is a LogStream for build metadata.
	StreamMeta Stream = 4
)

func ParseStream

func ParseStream(name string) (Stream, error)

ParseStream parses a Stream by name.

func (Stream) String

func (s Stream) String() string

func (Stream) Valid

func (s Stream) Valid() bool

Valid returns whether the stream is valid.