Permalink
Browse files

update documentation

  • Loading branch information...
z0mbie42 committed Feb 7, 2019
1 parent 89aa7db commit 7285523e4ce8d5ca344927aef7ab5a514174adcb
Showing with 91 additions and 277 deletions.
  1. +4 −4 array.go
  2. +1 −1 benchmarks_test.go
  3. +2 −2 binary_test.go
  4. +13 −80 doc.go
  5. +18 −20 event.go
  6. +48 −48 log_example_test.go
  7. +1 −1 log_test.go
  8. +1 −1 logger.go
  9. +1 −1 loglevel.go
  10. +1 −1 version.go
  11. +1 −1 writer.go
  12. +0 −57 writer_syslog.go
  13. +0 −60 writer_syslog_test.go
@@ -43,9 +43,9 @@ func (e *Event) Arr() *Array {
return a
}

// MarshalZerologArray method here is no-op - since data is
// MarshalRzArray method here is no-op - since data is
// already in the needed format.
func (*Array) MarshalZerologArray(*Array) {
func (*Array) MarshalRzArray(*Array) {
}

func (a *Array) write(dst []byte) []byte {
@@ -62,7 +62,7 @@ func (a *Array) write(dst []byte) []byte {
// interface and append append it to the array.
func (a *Array) Object(obj LogObjectMarshaler) *Array {
e := Dict()
obj.MarshalZerologObject(e)
obj.MarshalRzObject(e)
e.buf = enc.AppendEndMarker(e.buf)
a.buf = append(enc.AppendArrayDelim(a.buf), e.buf...)
putEvent(e)
@@ -186,7 +186,7 @@ func (a *Array) Float64(f float64) *Array {
return a
}

// Time append append t formated as string using zerolog.TimeFieldFormat.
// Time append append t formated as string using rz.TimeFieldFormat.
func (a *Array) Time(t time.Time) *Array {
a.buf = enc.AppendTime(enc.AppendArrayDelim(a.buf), t, a.timeFieldFormat)
return a
@@ -95,7 +95,7 @@ type obj struct {
priv int
}

func (o obj) MarshalZerologObject(e *Event) {
func (o obj) MarshalRzObject(e *Event) {
e.String("Pub", o.Pub).
String("Tag", o.Tag).
Int("priv", o.priv)
@@ -219,7 +219,7 @@ type User struct {
Created time.Time
}

func (u User) MarshalZerologObject(e *Event) {
func (u User) MarshalRzObject(e *Event) {
e.Str("name", u.Name).
Int("age", u.Age).
Time("created", u.Created)
@@ -406,7 +406,7 @@ type Price struct {
unit string
}

func (p Price) MarshalZerologObject(e *Event) {
func (p Price) MarshalRzObject(e *Event) {
denom := uint64(1)
for i := 0; i < p.prec; i++ {
denom *= 10
93 doc.go
@@ -4,96 +4,29 @@
//
// import "github.com/bloom42/rz-go/log"
//
// log.Info().Msg("hello world")
// // Output: {"time":1494567715,"level":"info","message":"hello world"}
// log.Info("hello world", nil)
// // Output: {"timestamp":"2019-02-07T09:30:07Z","level":"info","message":"hello world"}
//
// NOTE: To import the global logger, import the "log" subpackage "github.com/bloom42/rz-go/log".
//
// Fields can be added to log messages:
//
// log.Info().Str("foo", "bar").Msg("hello world")
// // Output: {"time":1494567715,"level":"info","message":"hello world","foo":"bar"}
// log.Info("hello world", func(e *rz.Event) { e.String("foo", "bar") })
// // Output: {"timestamp":"2019-02-07T09:30:07Z","level":"info","message":"hello world","foo":"bar"}
//
// Create logger instance to manage different outputs:
//
// logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
// logger.Info().
// Str("foo", "bar").
// Msg("hello world")
// // Output: {"time":1494567715,"level":"info","message":"hello world","foo":"bar"}
// logger := rz.New()
// log.Info("hello world", func(e *rz.Event) {
// e.String("foo", "bar") })
// })
// // Output: {"timestamp":"2019-02-07T09:30:07Z","level":"info","message":"hello world","foo":"bar"}
//
// Sub-loggers let you chain loggers with additional context:
//
// sublogger := log.With().Str("component": "foo").Logger()
// sublogger.Info().Msg("hello world")
// sublogger := log.Config(rz.With(func(e *Event) {
// e.Str("component": "foo")
// }))
// sublogger.Info("hello world", nil)
// // Output: {"time":1494567715,"level":"info","message":"hello world","component":"foo"}
//
// Level logging
//
// zerolog.SetGlobalLevel(zerolog.InfoLevel)
//
// log.Debug().Msg("filtered out message")
// log.Info().Msg("routed message")
//
// if e := log.Debug(); e.Enabled() {
// // Compute log output only if enabled.
// value := compute()
// e.Str("foo": value).Msg("some debug message")
// }
// // Output: {"level":"info","time":1494567715,"routed message"}
//
// Customize automatic field names:
//
// log.TimestampFieldName = "t"
// log.LevelFieldName = "p"
// log.MessageFieldName = "m"
//
// log.Info().Msg("hello world")
// // Output: {"t":1494567715,"p":"info","m":"hello world"}
//
// Log with no level and message:
//
// log.Log().Str("foo","bar").Msg("")
// // Output: {"time":1494567715,"foo":"bar"}
//
// Add contextual fields to global Logger:
//
// log.Logger = log.With().Str("foo", "bar").Logger()
//
// Sample logs:
//
// sampled := log.Sample(&zerolog.BasicSampler{N: 10})
// sampled.Info().Msg("will be logged every 10 messages")
//
// Log with contextual hooks:
//
// // Create the hook:
// type SeverityHook struct{}
//
// func (h SeverityHook) Run(e *zerolog.Event, level zerolog.Level, msg string) {
// if level != zerolog.NoLevel {
// e.Str("severity", level.String())
// }
// }
//
// // And use it:
// var h SeverityHook
// log := zerolog.New(os.Stdout).Hook(h)
// log.Warn().Msg("")
// // Output: {"level":"warn","severity":"warn"}
//
//
// Caveats
//
// There is no fields deduplication out-of-the-box.
// Using the same key multiple times creates new key in final JSON each time.
//
// logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
// logger.Info().
// Timestamp().
// Msg("dup")
// // Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}
//
// However, it’s not a big deal though as JSON accepts dup keys,
// the last one prevails.
package rz
@@ -51,13 +51,13 @@ func putEvent(e *Event) {
// LogObjectMarshaler provides a strongly-typed and encoding-agnostic interface
// to be implemented by types used with Event/Context's Object methods.
type LogObjectMarshaler interface {
MarshalZerologObject(e *Event)
MarshalRzObject(e *Event)
}

// LogArrayMarshaler provides a strongly-typed and encoding-agnostic interface
// to be implemented by types used with Event/Context's Array methods.
type LogArrayMarshaler interface {
MarshalZerologArray(a *Array)
MarshalRzArray(a *Array)
}

func newEvent(w LevelWriter, level LogLevel) *Event {
@@ -95,7 +95,7 @@ func (e *Event) Fields(fields map[string]interface{}) *Event {
}

// Dict adds the field key with a dict to the event context.
// Use zerolog.Dict() to create the dictionary.
// Use rz.Dict() to create the dictionary.
func (e *Event) Dict(key string, dict *Event) *Event {
if e == nil {
return e
@@ -114,7 +114,7 @@ func Dict() *Event {
}

// Array adds the field key with an array to the event context.
// Use zerolog.Arr() to create the array or pass a type that
// Use Event.Arr() to create the array or pass a type that
// implement the LogArrayMarshaler interface.
func (e *Event) Array(key string, arr LogArrayMarshaler) *Event {
if e == nil {
@@ -126,15 +126,15 @@ func (e *Event) Array(key string, arr LogArrayMarshaler) *Event {
a = aa
} else {
a = e.Arr()
arr.MarshalZerologArray(a)
arr.MarshalRzArray(a)
}
e.buf = a.write(e.buf)
return e
}

func (e *Event) appendObject(obj LogObjectMarshaler) {
e.buf = enc.AppendBeginMarker(e.buf)
obj.MarshalZerologObject(e)
obj.MarshalRzObject(e)
e.buf = enc.AppendEndMarker(e.buf)
}

@@ -153,7 +153,7 @@ func (e *Event) EmbedObject(obj LogObjectMarshaler) *Event {
if e == nil {
return e
}
obj.MarshalZerologObject(e)
obj.MarshalRzObject(e)
return e
}

@@ -253,13 +253,11 @@ func (e *Event) Errors(key string, errs []error) *Event {

// Err adds the field "error" with serialized err to the *Event context.
// If err is nil, no field is added.
// To customize the key name, change zerolog.ErrorFieldName.
//
// To customize the key name, change zerolog.ErrorFieldName.
//
// If Stack() has been called before and zerolog.ErrorStackMarshaler is defined,
// To customize the key name, uze rz.ErrorFieldName.
////
// If Stack() has been called before and rz.ErrorStackMarshaler is defined,
// the err is passed to ErrorStackMarshaler and the result is appended to the
// zerolog.ErrorStackFieldName.
// rz.ErrorStackFieldName.
func (e *Event) Err(err error) *Event {
if e == nil {
return e
@@ -535,7 +533,7 @@ func (e *Event) Timestamp() *Event {
return e
}

// Time adds the field key with t formated as string using zerolog.TimeFieldFormat.
// Time adds the field key with t formated as string using rz.TimeFieldFormat.
func (e *Event) Time(key string, t time.Time) *Event {
if e == nil {
return e
@@ -544,7 +542,7 @@ func (e *Event) Time(key string, t time.Time) *Event {
return e
}

// Times adds the field key with t formated as string using zerolog.TimeFieldFormat.
// Times adds the field key with t formated as string using rz.TimeFieldFormat.
func (e *Event) Times(key string, t []time.Time) *Event {
if e == nil {
return e
@@ -553,8 +551,8 @@ func (e *Event) Times(key string, t []time.Time) *Event {
return e
}

// Dur adds the field key with duration d stored as zerolog.DurationFieldUnit.
// If zerolog.DurationFieldInteger is true, durations are rendered as integer
// Dur adds the field key with duration d stored as rz.DurationFieldUnit.
// If rz.DurationFieldInteger is true, durations are rendered as integer
// instead of float.
func (e *Event) Dur(key string, d time.Duration) *Event {
if e == nil {
@@ -564,8 +562,8 @@ func (e *Event) Dur(key string, d time.Duration) *Event {
return e
}

// Durs adds the field key with duration d stored as zerolog.DurationFieldUnit.
// If zerolog.DurationFieldInteger is true, durations are rendered as integer
// Durs adds the field key with duration d stored as rz.DurationFieldUnit.
// If rz.DurationFieldInteger is true, durations are rendered as integer
// instead of float.
func (e *Event) Durs(key string, d []time.Duration) *Event {
if e == nil {
@@ -602,7 +600,7 @@ func (e *Event) Interface(key string, i interface{}) *Event {
return e
}

// Caller adds the file:line of the caller with the zerolog.CallerFieldName key.
// Caller adds the file:line of the caller with the rz.CallerFieldName key.
func (e *Event) Caller() *Event {
e.caller = true
return e
Oops, something went wrong.

0 comments on commit 7285523

Please sign in to comment.