logberry: github.com/BellerophonMobile/logberry Index | Files | Directories

package logberry

import "github.com/BellerophonMobile/logberry"

Package logberry implements a structured logging framework. It is focused on generating logs, rather than managing them, and tries to be lightweight while capturing more semantics and structure than is typical, in readable and easily parsed forms.

There are four central concepts/objects/interfaces:

D              - Data to be published with an event.
Task           - A component, function, or logic path generating events.
OutputDriver   - Serializer for publishing events.
Root           - An interface between Tasks and OutputDrivers.

Also important are two less fundamental but included concepts/objects:

Error          - A generic structured error report.
BuildMetadata  - A simple representation of the build environment.

Higher level documentation is available from the repository and README:

https://github.com/BellerophonMobile/logberry

Index

Package Files

D.go Error.go ErrorListener.go Event.go EventData.go JSONOutput.go OutputDriver.go Root.go Task.go TextOutput.go package.go

Constants

const (
    BEGIN         string = "begin"
    END           string = "end"
    CONFIGURATION string = "configuration"
    READY         string = "ready"
    STOPPED       string = "stopped"
    INFO          string = "info"
    SUCCESS       string = "success"
    WARNING       string = "warning"
    ERROR         string = "error"
)

These strings are common classes of events, used in the Task event generation functions to identify types of occurrences.

func IsError Uses

func IsError(e error, code ...string) bool

IsError checks if the given error is a Logberry Error tagged with any of the given codes, returning true if so and false otherwise.

type D Uses

type D map[string]interface{}

D is a convenience type to be used for quickly structuring simple data to be logged.

type DBuilder Uses

type DBuilder interface {
    D() D
}

A DBuilder is a type that can return logberry data when logged.

type Error Uses

type Error struct {

    // An optional identifier for differentiating classes of errors
    Code string

    // Human-oriented description of the fault
    Message string

    // Inputs, parameters, and other data associated with the fault
    Data EventDataMap

    // The source code file and line number where the error occurred
    Source *Position

    // Optional link to a preceding error underlying the fault
    Cause error `logberry:"quiet"`

    // Whether or not this error has already been reported
    Reported bool `logberry:"quiet"`
}

Error captures structured information about a fault.

func NewError Uses

func NewError(msg string, data ...interface{}) *Error

NewError generates a new Error capturing the given human-oriented message and optionally structured data associated with this fault. The source code position to be reported by this Error is the point at which NewError was called.

func WrapError Uses

func WrapError(msg string, err error, data ...interface{}) *Error

WrapError generates a new Error capturing the given human-oriented message, a preceding error which caused this higher level fault, and optionally structured data associated with this fault. The source code position to be reported by this Error is the point at which WrapError was called.

func (*Error) Error Uses

func (e *Error) Error() string

Error returns a human-oriented serialization of the error. It does not report the wrapped cause, if any. That must be retrieved and reported manually.

func (*Error) Locate Uses

func (e *Error) Locate(skip int)

Locate sets the source code position to be reported with this error as that point where the Locate call is made. It should not generally be necessary to invoke this manually when using Logberry.

func (*Error) SetCode Uses

func (e *Error) SetCode(code string) *Error

SetCode associates the error with a particular error class string.

func (*Error) String Uses

func (e *Error) String() string

String returns a human-oriented serialization of the error. It is the same as Error().

type ErrorListener Uses

type ErrorListener interface {
    Error(err error)
}

An ErrorListener is registered to Roots and notified of internal logging errors. Examples include an inability to write to disk, or contact a logging server. That notification could be utilized to prompt the administrator in some way or take other action. It is an error with unspecified behavior to add an ErrorListener to more than one Root simultaneously.

type Event Uses

type Event struct {
    TaskID   uint64
    ParentID uint64

    Component string

    Event   string
    Message string
    Data    EventDataMap

    Timestamp time.Time
}

Event captures an annotated occurrence or message, a log entry.

type EventData Uses

type EventData interface {
    WriteTo(io.Writer)
}

func Copy Uses

func Copy(data interface{}) EventData

type EventDataBool Uses

type EventDataBool bool

func (EventDataBool) WriteTo Uses

func (x EventDataBool) WriteTo(out io.Writer)

type EventDataFloat64 Uses

type EventDataFloat64 float64

func (EventDataFloat64) WriteTo Uses

func (x EventDataFloat64) WriteTo(out io.Writer)

type EventDataInt64 Uses

type EventDataInt64 int64

func (EventDataInt64) WriteTo Uses

func (x EventDataInt64) WriteTo(out io.Writer)

type EventDataMap Uses

type EventDataMap map[string]EventData

func Aggregate Uses

func Aggregate(data []interface{}) EventDataMap

func (EventDataMap) Aggregate Uses

func (x EventDataMap) Aggregate(data interface{}) EventDataMap

func (EventDataMap) String Uses

func (x EventDataMap) String() string

func (EventDataMap) WriteTo Uses

func (x EventDataMap) WriteTo(out io.Writer)

type EventDataSlice Uses

type EventDataSlice []EventData

func (EventDataSlice) WriteTo Uses

func (x EventDataSlice) WriteTo(out io.Writer)

type EventDataString Uses

type EventDataString string

func (EventDataString) WriteTo Uses

func (x EventDataString) WriteTo(out io.Writer)

type EventDataUInt64 Uses

type EventDataUInt64 uint64

func (EventDataUInt64) WriteTo Uses

func (x EventDataUInt64) WriteTo(out io.Writer)

type JSONOutput Uses

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

JSONOutput is an OutputDriver that writes log events in JSON.

func NewJSONOutput Uses

func NewJSONOutput(w io.Writer) *JSONOutput

NewJSONOutput creates a new JSONOutput targeted at the given Writer. DifferentialTime defaults to false.

func (*JSONOutput) Attach Uses

func (x *JSONOutput) Attach(root *Root)

Attach notifies the OutputDriver of its Root. It should only be called by a Root.

func (*JSONOutput) Detach Uses

func (x *JSONOutput) Detach()

Detach notifies the OutputDriver that it has been removed from its Root. It should only be called by a root.

func (*JSONOutput) Event Uses

func (x *JSONOutput) Event(event *Event)

Event outputs a generated log entry, as called by a Root or a chaining OutputDriver.

type OutputDriver Uses

type OutputDriver interface {
    Attach(root *Root)
    Detach()
    Event(event *Event)
}

An OutputDriver is registered to Roots and receives log events to export, e.g., writing to disk, screen, or sending to a server. To do so, an OutputDriver is created and then passed to the AddOutputDriver function of a Root. That Root will then call the OutputDriver's Attach() function to notify it of its context. Unless specifically noted otherwise by the implementation, it is an error with unspecified behavior to add an OutputDriver instance to more than one Root simultaneously.

type Position Uses

type Position struct {
    File string
    Line int
}

type Root Uses

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

Root pushes events to OutputDrivers in a thread safe and receipt ordered fashion but in a separate, dedicated goroutine. This may be useful for logging outputs that may take some time, e.g., pushing to a logging server. At the conclusion of the program Stop should be called on the root to ensure that all of its events are flushed before terminating.

var Std *Root

Std is the default Root created at startup.

func NewRoot Uses

func NewRoot(buffer int) *Root

NewRoot creates a new Root. The buffer parameter indicates the size of the channel buffer connecting event generation to outputs. The goroutine that creates the Root should defer a call to Stop() to ensure that all events are pushed.

func (*Root) AddErrorListener Uses

func (x *Root) AddErrorListener(listener ErrorListener)

AddErrorListener includes the given listener among those to which internal logging errors are reported.

func (*Root) AddOutputDriver Uses

func (x *Root) AddOutputDriver(driver OutputDriver)

AddOutputDriver includes the given additional output in those to which this Root forwards events. This is not thread safe with event generation, drivers are assumed to be attached in serial at startup.

func (*Root) ClearErrorListeners Uses

func (x *Root) ClearErrorListeners()

ClearErrorListeners removes all of the registered listeners.

func (*Root) ClearOutputDrivers Uses

func (x *Root) ClearOutputDrivers()

ClearOutputDrivers removes all of the currently registered outputs. This is not thread safe with event generation, drivers are assumed to be managed in serial at startup.

func (*Root) Component Uses

func (x *Root) Component(component string, data ...interface{}) *Task

Component creates a new top level Task under this Root, representing a grouping of related functionality.

func (*Root) InternalError Uses

func (x *Root) InternalError(err error)

InternalError reports an internal logging error. It is generally to be used only by OutputDrivers.

func (*Root) SetErrorListener Uses

func (x *Root) SetErrorListener(listener ErrorListener)

SetErrorListener makes the given listener the only one for this Root. It is identical to calling x.ClearErrorListeners() and then x.AddErrorListener(listener).

func (*Root) SetOutputDriver Uses

func (x *Root) SetOutputDriver(driver OutputDriver)

SetOutputDriver makes the given driver the only output for this root. It is identical to calling x.ClearOutputDrivers() and then x.AddOutputDriver(driver).

func (*Root) Stop Uses

func (x *Root) Stop()

Stop shuts down the Root. Its internal channel is closed, and newly generated log events no longer forwarded to output drivers. Any previously buffered events are processed before Stop exits.

func (*Root) Task Uses

func (x *Root) Task(activity string, data ...interface{}) *Task

Task creates a new top level Task under this Root, representing a particular line of activity.

type StdErrorListener Uses

type StdErrorListener struct{}

func (*StdErrorListener) Error Uses

func (x *StdErrorListener) Error(err error)

type Task Uses

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

Task represents a particular component, function, or activity. In general a Task is meant to be used within a single thread of execution, and the calling code is responsible for managing any concurrent manipulation.

var Main *Task

Main is the default Task created at startup, roughly intended to represent main program execution.

func (*Task) AddData Uses

func (x *Task) AddData(data ...interface{}) *Task

AddData incorporates the given data into that associated and reported with this Task. This call does not generate a log event. The host Task is passed through as the return. Among other things, this function is useful to silently accumulate data into the Task as it proceeds, to be reported when it concludes.

func (*Task) Component Uses

func (x *Task) Component(component string, data ...interface{}) *Task

Component creates a new Task object representing related long-lived functionality, rather than a directed, tightly scoped line of computation. Parameter component should be a short lowercase string identifying the class, module, or other component that this Task represents. The activity text of this Task is set to be "Component " + component.

func (*Task) Error Uses

func (x *Task) Error(cause error, data ...interface{}) *Error

Error generates an error log event reporting an unrecoverable fault in an activity or component. If the given error is not a Logberry Error that has already been logged then it will be reported. An error is returned wrapping the original error with a message reporting that the Task's activity has failed. Continuing to use the Task is discouraged. The variadic data parameter is aggregated as a D and embedded in the generated error. It and the data permanently associated with the Task is reported with the event. The reported source code position of the generated task error is adjusted to be the event invocation.

func (*Task) Event Uses

func (x *Task) Event(event string, msg string, data ...interface{})

Event generates a user-specified log event. Parameter event tags the class of the event, generally a short lowercase whitespace-free identifier. A human-oriented text message is given as the msg parameter. This should generally be static, short, use sentence capitalization but no terminating punctuation, and not itself include any data, which is better left to the structured data. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Failure Uses

func (x *Task) Failure(msg string, data ...interface{}) *Error

Failure generates an error log event reporting an unrecoverable fault. Failure and Error are essentially the same, the difference being that Failure is the first point of fault while Error takes an underlying error typically returned from another function or component. An error is returned reporting that the activity or component represented by the Task has failed due to the underlying cause given in the message. Continuing to use the Task is discouraged. The variadic data parameter is aggregated as a D and embedded in the generated task error. It and the data permanently associated with the Task is reported with the event. The reported source code position of the generated task error is adjusted to be the event invocation.

func (*Task) Finalized Uses

func (x *Task) Finalized(data ...interface{})

Finalized generates an end log event reporting that the component the Task represents has ceased. It is generally intended to be used for components, while Success is used for discrete activities. Continuing to use the Task is discouraged. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Info Uses

func (x *Task) Info(msg string, data ...interface{})

Info generates an informational log event. A human-oriented text message is given as the msg parameter. This should generally be static, short, use sentence capitalization but no terminating punctuation, and not itself include any data, which is better left to the structured data. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Ready Uses

func (x *Task) Ready(data ...interface{})

Ready generates a ready log event reporting that the activity or component the Task represents is initialized and prepared to begin. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Stopped Uses

func (x *Task) Stopped(data ...interface{})

Stopped generates a stopped log event reporting that the activity or component the Task represents has paused or shutdown. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Success Uses

func (x *Task) Success(data ...interface{}) error

Success generates a success log event reporting that the activity the Task represents has concluded successfully. It always returns nil. Continuing to use the Task is discouraged. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) Task Uses

func (x *Task) Task(activity string, data ...interface{}) *Task

Task creates a new sub-task. Parameter activity should be a short natural language description of the work that the Task represents, without any terminating punctuation.

func (*Task) Warning Uses

func (x *Task) Warning(msg string, data ...interface{})

Warning generates a warning log event indicating that a fault was encountered but the task is proceeding acceptably. This should generally be static, short, use sentence capitalization but no terminating punctuation, and not itself include any data, which is better left to the structured data. The variadic data parameter is aggregated as a D and reported with the event, as is the data permanently associated with the Task. The given data is not associated to the Task permanently.

func (*Task) WrapError Uses

func (x *Task) WrapError(msg string, cause error, data ...interface{}) *Error

type TextOutput Uses

type TextOutput struct {
    Program string

    Color bool

    IDOffset   int
    DataOffset int
    // contains filtered or unexported fields
}

TextOutput is an OutputDriver that writes out log events in a structured but more or less human readable form. It has the following public properties:

Program                    String label of the executing program.

Color                      Set to true/false to enable/disable
                           outputting terminal color codes as
                           part of formatting log entries.
                           Defaults to false except for when
                           constructed via NewStdOutput and
                           NewErrOutput as below, in which case
                           it defaults to true iff the underlying
                           streams are terminals.

IDOffset                   The column at which to start printing
                           identifying information.

DataOffset                 The column at which to start printing
                           event data.

The default offsets are designed to wrap well on either 80 column or very wide terminals, generally putting each event on one or two lines respectively.

func NewErrOutput Uses

func NewErrOutput(program string) *TextOutput

NewErrOutput creates a new TextOutput attached to stderr.

func NewStdOutput Uses

func NewStdOutput(program string) *TextOutput

NewStdOutput creates a new TextOutput attached to stdout.

func NewTextOutput Uses

func NewTextOutput(w io.Writer, program string) *TextOutput

NewTextOutput creates a new TextOutput attached to the given writer.

func (*TextOutput) Attach Uses

func (o *TextOutput) Attach(root *Root)

Attach notifies the OutputDriver of its Root. It should only be called by a Root.

func (*TextOutput) Detach Uses

func (o *TextOutput) Detach()

Detach notifies the OutputDriver that it has been removed from its Root. It should only be called by a root.

func (*TextOutput) Event Uses

func (o *TextOutput) Event(event *Event)

Event outputs a generated log entry, as called by a Root or a chaining OutputDriver.

Directories

PathSynopsis
env
env/util
gocuioutput
sseoutput
sseoutput/test
terminalPackage terminal provides platform specific terminal detection functions.
tests

Package logberry imports 15 packages (graph) and is imported by 7 packages. Updated 2018-10-29. Refresh now. Tools for package owners.