Documentation
¶
Overview ¶
Package eventlog standardizes structured JSON logging using zerolog as the underlying logging framework.
Zerolog is initialized with the following settings:
- the following standard logger field names are shortened
- Timestamp -> t
- Level -> l
- Message -> m
- Error -> err
- Unix time format is used for performance reasons - seconds granularity is sufficient for log events
- an error stack marshaller is configured
- time.Duration fields are rendered as int instead float because it's more efficient
- each log event is tagged with an XID via a field named "x"
Example ¶
// Define your application events
const (
Foo = "01DFBM3VV1N11HQB04WZRA4R88"
)
// Define your strongly typed logging functions
FooInfoLogger := func(logger *zerolog.Logger) func(id FooID, msg string, tags ...string) {
log := eventlog.NewLogger(Foo, logger, zerolog.InfoLevel)
return func(id FooID, msg string, tags ...string) {
log(id, msg, tags...)
}
}
// Create your application logging functions
logger := zerolog.New(os.Stdout)
logFooInfo := FooInfoLogger(&logger)
// log some events
fooID := FooID("01DFBMTSW3J58NG6VGPQ3WTFFZ")
// tagging events with ULIDs makes it easy to find where the event was logged from in the code
logFooInfo(fooID, "MSG#1", "01DFBQA67JKT2HKGDVRN3QN38R")
logFooInfo(fooID, "MSG#2", "01DFBQ9DWKFBA7KJRBZVGV69NN", "tag-2")
Output: {"l":"info","n":"01DFBM3VV1N11HQB04WZRA4R88","g":["01DFBQA67JKT2HKGDVRN3QN38R"],"d":{"id":"01DFBMTSW3J58NG6VGPQ3WTFFZ"},"m":"MSG#1"} {"l":"info","n":"01DFBM3VV1N11HQB04WZRA4R88","g":["01DFBQ9DWKFBA7KJRBZVGV69NN","tag-2"],"d":{"id":"01DFBMTSW3J58NG6VGPQ3WTFFZ"},"m":"MSG#2"}
Index ¶
Examples ¶
Constants ¶
const ( Name = "n" // event name - should be a XID Component = "c" // component name - should be a XID XID = "x" // event instance XID )
standard top level logger field names
Variables ¶
This section is empty.
Functions ¶
func ForComponent ¶
ForComponent returns a new logger with the component field 'c' set to the specified value. To ensure uniqueness, use ULIDs.
func ForEvent ¶
ForEvent returns a new logger with the event type ID field 'n' set to the specified value.
The event should be unique. To ensure uniqueness, use ULIDs.
func NewZeroLogger ¶
NewZeroLogger constructs a new zerolog.Logger that is configured to add the following fields:
- timestamp in UNIX time format
- event XID
Example log message:
{"z":"01DFBGCFD9WD29SGRJPK8KZKQS","t":1562680638,"m":"Hello World"}
where z -> event XID
t -> event timestamp
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error wraps an underlying error to implement `zerolog.LogObjectMarshaler` interface
func (Error) MarshalZerologObject ¶
MarshalZerologObject implements `zerolog.LogObjectMarshaler` interface
type Logger ¶
type Logger func(data zerolog.LogObjectMarshaler, msg string, tags ...string)
Logger is used to log events using a consistent and standardized structure. Use the `NewLogger()` constructor function to create new Logger functions.
- log event level is encapsulated by the Logger function. - event data is optional, i.e., nil may be supplied. - events can be tagged
- tagging use cases: tracing, grouping related events, tagging source code locations, etc
func NewLogger ¶
NewLogger creates a new function used to log events using a standardized structure that supports use cases for automated monitoring, alerting, querying, and analytics. Having a standardized structure makes it easier to build standardized tools. The goal is to get more value out of log events by enabling the log events to be processed programmatically.
The event object data is logged as an event dictionary, using the event name as the key. The event name must be globally unique - it is recommended to use XID as the event name. The event data structure should be designed to be as stable as possible. Treat the event data structure as an interface because monitors, tools, queries, and other tools may depend on it. Not all events may have event data.
Example application event
{
"l": "error", -------------------------------------- event level
"n": "01DE2Z4E07E4T0GJJXCG8NN6A0", ----------------- event name
"d": { --------------------------------------------- event data (optional)
"id": "01DE379HHNVHQE5G6NHN2BBKAT", -------------- event data (optional)
}, ------------------------------------------------- event data (optional)
"g": ["tag-a","tag-b"], ---------------------------- event tags (optional)
"m": "health check failed" ------------------------- event short description
}
Source Files