Update docs for V5

Author: nhooyr

README.md

@@ -23,12 +23,12 @@ go get cdr.dev/slog
     - Prints multiline fields and errors nicely
 - Machine readable JSON output
 - [GCP Stackdriver](https://godoc.org/cdr.dev/slog/sloggers/slogstackdriver) support
-- [Tee](https://godoc.org/cdr.dev/slog#Tee) multiple loggers
 - [Stdlib](https://godoc.org/cdr.dev/slog#Stdlib) log adapter
 - Skip caller frames with [slog.Helper](https://godoc.org/cdr.dev/slog#Helper)
 - Encodes values as if with `json.Marshal`
 - Transparently log [opencensus](https://godoc.org/go.opencensus.io/trace) trace and span IDs
 - [Single dependency](https://godoc.org/cdr.dev/slog?imports) on go.opencensus.io
+- Log to multiple sinks
 
 ## Example
 
@@ -92,10 +92,8 @@ Here is a list of reasons how we improved on zap with slog.
 
 1. Simple and easy to extend
     - A new backend only has to implement the simple Sink interface.
-    - The logger type provides a nice API around Sink and itself implements
-      Sink allowing for composition and wrapping. E.g. one could implement
-      a Sink that wraps around another sink to ensure no logs with a given
-      component are logged.
+    - The Logger type provides a nice API around Sink but also implements
+      Sink to allow for composition.
     - zap is hard and confusing to extend. There are too many structures and configuration options.
 
 1. Structured logging of Go structures with `json.Marshal`

internal/entryhuman/entry.go

@@ -58,10 +58,10 @@ func Fmt(w io.Writer, ent slog.SinkEntry) string {
 	level = c(w, levelColor(ent.Level)).Sprint(level)
 	ents += fmt.Sprintf("%v\t", level)
 
-	if len(ent.Names) > 0 {
-		component := "(" + quoteKey(strings.Join(ent.Names, ".")) + ")"
-		component = c(w, color.FgMagenta).Sprint(component)
-		ents += fmt.Sprintf("%v\t", component)
+	if len(ent.LoggerNames) > 0 {
+		loggerName := "(" + quoteKey(strings.Join(ent.LoggerNames, ".")) + ")"
+		loggerName = c(w, color.FgMagenta).Sprint(loggerName)
+		ents += fmt.Sprintf("%v\t", loggerName)
 	}
 
 	loc := fmt.Sprintf("<%v:%v>", filepath.Base(ent.File), ent.Line)

internal/entryhuman/entry_test.go

@@ -51,8 +51,8 @@ line2`)
 		t.Parallel()
 
 		test(t, slog.SinkEntry{
-			Level: slog.LevelWarn,
-			Names: []string{"named", "meow"},
+			Level:       slog.LevelWarn,
+			LoggerNames: []string{"named", "meow"},
 		}, `0001-01-01 00:00:00.000 [WARN]	(named.meow)	<.:0>	""`)
 	})
 

map.go

@@ -147,3 +147,10 @@ func (p *xerrorPrinter) write(s string) {
 		p.e.Loc = s
 	}
 }
+
+func (m Map) append(m2 Map) Map {
+	m3 := make(Map, 0, len(m)+len(m2))
+	m3 = append(m3, m...)
+	m3 = append(m3, m2...)
+	return m3
+}

slog.go

@@ -4,8 +4,10 @@
 //
 // The examples are the best way to understand how to use this library effectively.
 //
-// This package provides a high level API around the Sink interface.
-// The implementations are in the sloggers subdirectory.
+// The Logger type implements a high level API around the Sink interface.
+// Logger implements Sink as well to allow composition.
+//
+// Implementations of the Sink interface are available in the sloggers subdirectory.
 package slog // import "cdr.dev/slog"
 
 import (
@@ -37,7 +39,7 @@ func (l Logger) LogEntry(ctx context.Context, e SinkEntry) {
 	}
 
 	e.Fields = l.fields.append(e.Fields)
-	e.Names = appendName(e.Names, l.names...)
+	e.LoggerNames = appendNames(l.names, e.LoggerNames...)
 
 	for _, s := range l.sinks {
 		s.LogEntry(ctx, e)
@@ -51,16 +53,17 @@ func (l Logger) Sync() {
 	}
 }
 
-// Logger wraps Sink with a easy to use API.
+// Logger wraps Sink with a nice API to log entries.
 //
 // Logger is safe for concurrent use.
 type Logger struct {
+	sinks []Sink
+	level Level
+
 	names  []string
-	sinks  []Sink
-	skip   int
 	fields Map
-	level  Level
 
+	skip int
 	exit func(int)
 }
 
@@ -91,54 +94,42 @@ func (l Logger) Warn(ctx context.Context, msg string, fields ...Field) {
 
 // Error logs the msg and fields at LevelError.
 //
-// It will also Sync() before returning.
+// It will then Sync().
 func (l Logger) Error(ctx context.Context, msg string, fields ...Field) {
 	l.log(ctx, LevelError, msg, fields)
 	l.Sync()
 }
 
 // Critical logs the msg and fields at LevelCritical.
 //
-// It will also Sync() before returning.
+// It will then Sync().
 func (l Logger) Critical(ctx context.Context, msg string, fields ...Field) {
 	l.log(ctx, LevelCritical, msg, fields)
 	l.Sync()
 }
 
 // Fatal logs the msg and fields at LevelFatal.
 //
-// It will also Sync() before returning.
+// It will then Sync() and os.Exit(1).
 func (l Logger) Fatal(ctx context.Context, msg string, fields ...Field) {
 	l.log(ctx, LevelFatal, msg, fields)
 	l.Sync()
 	l.exit(1)
 }
 
-var helpers sync.Map
-
-// Helper marks the calling function as a helper
-// and skips it for source location information.
-// It's the slog equivalent of testing.TB.Helper().
-func Helper() {
-	_, _, fn := location(1)
-	helpers.LoadOrStore(fn, struct{}{})
-}
-
 // With returns a Logger that prepends the given fields on every
 // logged entry.
+//
 // It will append to any fields already in the Logger.
 func (l Logger) With(fields ...Field) Logger {
 	l.fields = l.fields.append(fields)
 	return l
 }
 
-// Named names the logger.
-// If there is already a name set, it will be joined by ".".
-// E.g. if the name is currently "my_component" and then later
-// the name "my_pkg" is set, then the final component will be
-// "my_component.my_pkg".
+// Named appends the name to the set names
+// on the logger.
 func (l Logger) Named(name string) Logger {
-	l.names = appendName(l.names, name)
+	l.names = appendNames(l.names, name)
 	return l
 }
 
@@ -149,6 +140,33 @@ func (l Logger) Leveled(level Level) Logger {
 	return l
 }
 
+func (l Logger) log(ctx context.Context, level Level, msg string, fields Map) {
+	ent := l.entry(ctx, level, msg, fields)
+	l.LogEntry(ctx, ent)
+}
+
+func (l Logger) entry(ctx context.Context, level Level, msg string, fields Map) SinkEntry {
+	ent := SinkEntry{
+		Time:        time.Now().UTC(),
+		Level:       level,
+		Message:     msg,
+		Fields:      fieldsFromContext(ctx).append(fields),
+		SpanContext: trace.FromContext(ctx).SpanContext(),
+	}
+	ent = ent.fillLoc(l.skip + 3)
+	return ent
+}
+
+var helpers sync.Map
+
+// Helper marks the calling function as a helper
+// and skips it for source location information.
+// It's the slog equivalent of testing.TB.Helper().
+func Helper() {
+	_, _, fn := location(1)
+	helpers.LoadOrStore(fn, struct{}{})
+}
+
 func (ent SinkEntry) fillFromFrame(f runtime.Frame) SinkEntry {
 	ent.Func = f.Function
 	ent.File = f.File
@@ -182,27 +200,14 @@ func location(skip int) (file string, line int, fn string) {
 	return file, line, f.Name()
 }
 
-func appendName(names []string, names2 ...string) []string {
-	names = append([]string(nil), names...)
-	names = append(names, names2...)
-	return names
-}
-
-func (l Logger) log(ctx context.Context, level Level, msg string, fields Map) {
-	ent := l.entry(ctx, level, msg, fields)
-	l.LogEntry(ctx, ent)
-}
-
-func (l Logger) entry(ctx context.Context, level Level, msg string, fields Map) SinkEntry {
-	ent := SinkEntry{
-		Time:        time.Now().UTC(),
-		Level:       level,
-		Message:     msg,
-		Fields:      fieldsFromContext(ctx).append(fields),
-		SpanContext: trace.FromContext(ctx).SpanContext(),
+func appendNames(names []string, names2 ...string) []string {
+	if len(names2) == 0 {
+		return names
 	}
-	ent = ent.fillLoc(l.skip + 3)
-	return ent
+	names3 := make([]string, 0, len(names)+len(names2))
+	names3 = append(names3, names...)
+	names3 = append(names3, names2...)
+	return names3
 }
 
 // Field represents a log field.
@@ -222,6 +227,7 @@ func M(fs ...Field) Map {
 }
 
 // Value represents a log value.
+//
 // Implement SlogValue in your own types to override
 // the value encoded when logging.
 type Value interface {
@@ -245,8 +251,9 @@ func fieldsFromContext(ctx context.Context) Map {
 }
 
 // With returns a context that contains the given fields.
-// Any logs written with the provided context will have
-// the given logs prepended.
+//
+// Any logs written with the provided context will have the given logs prepended.
+//
 // It will append to any fields already in ctx.
 func With(ctx context.Context, fields ...Field) context.Context {
 	f1 := fieldsFromContext(ctx)
@@ -262,9 +269,7 @@ type SinkEntry struct {
 	Level   Level
 	Message string
 
-	// Names represents the chain of names on the
-	// logger constructed with Named.
-	Names []string
+	LoggerNames []string
 
 	Func string
 	File string
@@ -279,6 +284,8 @@ type SinkEntry struct {
 type Level int
 
 // The supported log levels.
+//
+// The default level is Info.
 const (
 	LevelDebug Level = iota
 	LevelInfo
@@ -297,17 +304,11 @@ var levelStrings = map[Level]string{
 	LevelFatal:    "FATAL",
 }
 
+// String implements fmt.Stringer.
 func (l Level) String() string {
 	s, ok := levelStrings[l]
 	if !ok {
 		return fmt.Sprintf("slog.Level(%v)", int(l))
 	}
 	return s
 }
-
-func (f1 Map) append(f2 Map) Map {
-	f3 := make(Map, 0, len(f1)+len(f2))
-	f3 = append(f3, f1...)
-	f3 = append(f3, f2...)
-	return f3
-}

slog_test.go

@@ -103,7 +103,7 @@ func TestLogger(t *testing.T) {
 			Level:   slog.LevelInfo,
 			Message: "meow",
 
-			Names: []string{"hello", "hello2"},
+			LoggerNames: []string{"hello", "hello2"},
 
 			File: slogTestFile,
 			Func: "cdr.dev/slog_test.TestLogger.func3",

sloggers/slogjson/slogjson.go

@@ -1,18 +1,18 @@
-// Package slogjson contains the slogger that writes logs in a JSON format.
+// Package slogjson contains the slogger that writes logs in JSON.
 //
 // Format
 //
 //  {
 //    "ts": "2019-09-10T20:19:07.159852-05:00",
 //    "level": "INFO",
-//    "component": "comp.subcomp",
+//    "logger_names": ["comp", "subcomp"],
 //    "msg": "hi",
 //    "caller": "slog/examples_test.go:62",
 //    "func": "cdr.dev/slog/sloggers/slogtest_test.TestExampleTest",
 //    "trace": "<traceid>",
 //    "span": "<spanid>",
 //    "fields": {
-//      "myField": "fieldValue"
+//      "my_field": "field value"
 //    }
 //  }
 package slogjson // import "cdr.dev/slog/sloggers/slogjson"
@@ -53,8 +53,8 @@ func (s jsonSink) LogEntry(ctx context.Context, ent slog.SinkEntry) {
 		slog.F("func", ent.Func),
 	)
 
-	if len(ent.Names) > 0 {
-		m = append(m, slog.F("component", ent.Names))
+	if len(ent.LoggerNames) > 0 {
+		m = append(m, slog.F("logger_names", ent.LoggerNames))
 	}
 
 	if ent.SpanContext != (trace.SpanContext{}) {

sloggers/slogjson/slogjson_test.go

@@ -29,7 +29,7 @@ func TestMake(t *testing.T) {
 	l.Error(ctx, "line1\n\nline2", slog.F("wowow", "me\nyou"))
 
 	j := entryjson.Filter(b.String(), "ts")
-	exp := fmt.Sprintf(`{"level":"ERROR","msg":"line1\n\nline2","caller":"%v:29","func":"cdr.dev/slog/sloggers/slogjson_test.TestMake","component":["named"],"trace":"%v","span":"%v","fields":{"wowow":"me\nyou"}}
+	exp := fmt.Sprintf(`{"level":"ERROR","msg":"line1\n\nline2","caller":"%v:29","func":"cdr.dev/slog/sloggers/slogjson_test.TestMake","logger_names":["named"],"trace":"%v","span":"%v","fields":{"wowow":"me\nyou"}}
 `, slogjsonTestFile, s.SpanContext().TraceID, s.SpanContext().SpanID)
 	assert.Equal(t, exp, j, "entry")
 }

sloggers/slogstackdriver/slogstackdriver.go

@@ -1,4 +1,4 @@
-// Package slogstackdriver contains the slogger for GCP.
+// Package slogstackdriver contains the slogger for google cloud's stackdriver.
 package slogstackdriver // import "cdr.dev/slog/sloggers/slogstackdriver"
 
 import (
@@ -48,9 +48,9 @@ func (s stackdriverSink) LogEntry(ctx context.Context, ent slog.SinkEntry) {
 		}),
 	)
 
-	if len(ent.Names) > 0 {
+	if len(ent.LoggerNames) > 0 {
 		e = append(e, slog.F("logging.googleapis.com/operation", &logpb.LogEntryOperation{
-			Producer: strings.Join(ent.Names, "."),
+			Producer: strings.Join(ent.LoggerNames, "."),
 		}))
 	}