Documentation ¶
Overview ¶
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 ¶
- Constants
- func IsError(e error, code ...string) bool
- type D
- type DBuilder
- type Error
- type ErrorListener
- type Event
- type EventData
- type EventDataBool
- type EventDataFloat64
- type EventDataInt64
- type EventDataMap
- type EventDataSlice
- type EventDataString
- type EventDataUInt64
- type JSONOutput
- type OutputDriver
- type Position
- type Root
- func (x *Root) AddErrorListener(listener ErrorListener)
- func (x *Root) AddOutputDriver(driver OutputDriver)
- func (x *Root) ClearErrorListeners()
- func (x *Root) ClearOutputDrivers()
- func (x *Root) Component(component string, data ...interface{}) *Task
- func (x *Root) InternalError(err error)
- func (x *Root) SetErrorListener(listener ErrorListener)
- func (x *Root) SetOutputDriver(driver OutputDriver)
- func (x *Root) Stop()
- func (x *Root) Task(activity string, data ...interface{}) *Task
- type StdErrorListener
- type Task
- func (x *Task) AddData(data ...interface{}) *Task
- func (x *Task) Component(component string, data ...interface{}) *Task
- func (x *Task) Error(cause error, data ...interface{}) *Error
- func (x *Task) Event(event string, msg string, data ...interface{})
- func (x *Task) Failure(msg string, data ...interface{}) *Error
- func (x *Task) Finalized(data ...interface{})
- func (x *Task) Info(msg string, data ...interface{})
- func (x *Task) Ready(data ...interface{})
- func (x *Task) Stopped(data ...interface{})
- func (x *Task) Success(data ...interface{}) error
- func (x *Task) Task(activity string, data ...interface{}) *Task
- func (x *Task) Warning(msg string, data ...interface{})
- func (x *Task) WrapError(msg string, cause error, data ...interface{}) *Error
- type TextOutput
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.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type D ¶
type D map[string]interface{}
D is a convenience type to be used for quickly structuring simple data to be logged.
type DBuilder ¶
type DBuilder interface {
D() D
}
A DBuilder is a type that can return logberry data when logged.
type Error ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type ErrorListener ¶
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 ¶
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 EventDataBool ¶
type EventDataBool bool
func (EventDataBool) WriteTo ¶
func (x EventDataBool) WriteTo(out io.Writer)
type EventDataFloat64 ¶
type EventDataFloat64 float64
func (EventDataFloat64) WriteTo ¶
func (x EventDataFloat64) WriteTo(out io.Writer)
type EventDataInt64 ¶
type EventDataInt64 int64
func (EventDataInt64) WriteTo ¶
func (x EventDataInt64) WriteTo(out io.Writer)
type EventDataMap ¶
func Aggregate ¶
func Aggregate(data []interface{}) EventDataMap
func (EventDataMap) Aggregate ¶
func (x EventDataMap) Aggregate(data interface{}) EventDataMap
func (EventDataMap) String ¶
func (x EventDataMap) String() string
func (EventDataMap) WriteTo ¶
func (x EventDataMap) WriteTo(out io.Writer)
type EventDataSlice ¶
type EventDataSlice []EventData
func (EventDataSlice) WriteTo ¶
func (x EventDataSlice) WriteTo(out io.Writer)
type EventDataString ¶
type EventDataString string
func (EventDataString) WriteTo ¶
func (x EventDataString) WriteTo(out io.Writer)
type EventDataUInt64 ¶
type EventDataUInt64 uint64
func (EventDataUInt64) WriteTo ¶
func (x EventDataUInt64) WriteTo(out io.Writer)
type JSONOutput ¶
type JSONOutput struct {
// contains filtered or unexported fields
}
JSONOutput is an OutputDriver that writes log events in JSON.
func NewJSONOutput ¶
func NewJSONOutput(w io.Writer) *JSONOutput
NewJSONOutput creates a new JSONOutput targeted at the given Writer. DifferentialTime defaults to false.
func (*JSONOutput) Attach ¶
func (x *JSONOutput) Attach(root *Root)
Attach notifies the OutputDriver of its Root. It should only be called by a Root.
func (*JSONOutput) Detach ¶
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 ¶
func (x *JSONOutput) Event(event *Event)
Event outputs a generated log entry, as called by a Root or a chaining OutputDriver.
type OutputDriver ¶
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 Root ¶
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 ¶
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 ¶
func (x *Root) AddErrorListener(listener ErrorListener)
AddErrorListener includes the given listener among those to which internal logging errors are reported.
func (*Root) AddOutputDriver ¶
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 ¶
func (x *Root) ClearErrorListeners()
ClearErrorListeners removes all of the registered listeners.
func (*Root) ClearOutputDrivers ¶
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 ¶
Component creates a new top level Task under this Root, representing a grouping of related functionality.
func (*Root) InternalError ¶
InternalError reports an internal logging error. It is generally to be used only by OutputDrivers.
func (*Root) SetErrorListener ¶
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 ¶
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).
type StdErrorListener ¶
type StdErrorListener struct{}
func (*StdErrorListener) Error ¶
func (x *StdErrorListener) Error(err error)
type Task ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type TextOutput ¶
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 ¶
func NewErrOutput(program string) *TextOutput
NewErrOutput creates a new TextOutput attached to stderr.
func NewStdOutput ¶
func NewStdOutput(program string) *TextOutput
NewStdOutput creates a new TextOutput attached to stdout.
func NewTextOutput ¶
func NewTextOutput(w io.Writer, program string) *TextOutput
NewTextOutput creates a new TextOutput attached to the given writer.
func (*TextOutput) Attach ¶
func (o *TextOutput) Attach(root *Root)
Attach notifies the OutputDriver of its Root. It should only be called by a Root.
func (*TextOutput) Detach ¶
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 ¶
func (o *TextOutput) Event(event *Event)
Event outputs a generated log entry, as called by a Root or a chaining OutputDriver.