slog: Levels

This is the first commit for the new experimental package `slog`,
providing structured, leveled logging. golang.org/x/exp/slog
implements the draft proposal currently under discussion
at golang/go.

This commit defines Level and the related type AtomicLevel.

Change-Id: I2825a926dab14ea66a62313ca2b6cd5c1ca04683
Reviewed-on: https://go-review.googlesource.com/c/exp/+/426020
Run-TryBot: Jonathan Amsterdam <[email protected]>
Reviewed-by: Alan Donovan <[email protected]>

Author: jba

slog/level.go

@@ -0,0 +1,107 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package slog
+
+import (
+	"fmt"
+	"math"
+	"sync/atomic"
+)
+
+// A Level is the importance or severity of a log event.
+// The higher the level, the less important or severe the event.
+type Level int
+
+// The level numbers below don't really matter too much. Any system can map them
+// to another numbering scheme if it wishes. We picked them to satisfy two
+// constraints.
+//
+// First, we wanted to make it easy to work with verbosities instead of levels.
+// Since higher verbosities are less important, higher levels are as well.
+//
+// Second, we wanted some room between levels to accommodate schemes with named
+// levels between ours. For example, Google Cloud Logging defines a Notice level
+// between Info and Warn. Since there are only a few of these intermediate
+// levels, the gap between the numbers need not be large. We selected a gap of
+// 10, because the majority of humans have 10 fingers.
+//
+// The missing gap between Info and Debug has to do with verbosities again. It
+// is natural to think of verbosity 0 as Info, and then verbosity 1 is the
+// lowest level one would call Debug. The simple formula
+//   level = InfoLevel + verbosity
+// then works well to map verbosities to levels. That is,
+//
+//   Level(InfoLevel+0).String() == "INFO"
+//   Level(InfoLevel+1).String() == "DEBUG"
+//   Level(InfoLevel+2).String() == "DEBUG+1"
+//
+// and so on.
+
+// Names for common levels.
+const (
+	ErrorLevel Level = 10
+	WarnLevel  Level = 20
+	InfoLevel  Level = 30
+	DebugLevel Level = 31
+)
+
+// String returns a name for the level.
+// If the level has a name, then that name
+// in uppercase is returned.
+// If the level is between named values, then
+// an integer is appended to the uppercased name.
+// Examples:
+//
+//	WarnLevel.String() => "WARN"
+//	(WarnLevel-2).String() => "WARN-2"
+func (l Level) String() string {
+	str := func(base string, val Level) string {
+		if val == 0 {
+			return base
+		}
+		return fmt.Sprintf("%s%+d", base, val)
+	}
+
+	switch {
+	case l <= 0:
+		return fmt.Sprintf("!BADLEVEL(%d)", l)
+	case l <= ErrorLevel:
+		return str("ERROR", l-ErrorLevel)
+	case l <= WarnLevel:
+		return str("WARN", l-WarnLevel)
+	case l <= InfoLevel:
+		return str("INFO", l-InfoLevel)
+	default:
+		return str("DEBUG", l-DebugLevel)
+	}
+}
+
+// An AtomicLevel is Level that can be read and written safely by multiple
+// goroutines.
+// Use NewAtomicLevel to create one.
+type AtomicLevel struct {
+	val atomic.Int64
+}
+
+// NewAtomicLevel creates an AtomicLevel initialized to the given Level.
+func NewAtomicLevel(l Level) *AtomicLevel {
+	var r AtomicLevel
+	r.Set(l)
+	return &r
+}
+
+// Level returns r's level.
+// If r is nil, it returns the maximum level.
+func (r *AtomicLevel) Level() Level {
+	if r == nil {
+		return Level(math.MaxInt)
+	}
+	return Level(int(r.val.Load()))
+}
+
+// Set sets r's level to l.
+func (r *AtomicLevel) Set(l Level) {
+	r.val.Store(int64(l))
+}

slog/level_test.go

@@ -0,0 +1,49 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package slog
+
+import (
+	"math"
+	"testing"
+)
+
+func TestLevelString(t *testing.T) {
+	for _, test := range []struct {
+		in   Level
+		want string
+	}{
+		{0, "!BADLEVEL(0)"},
+		{ErrorLevel, "ERROR"},
+		{ErrorLevel - 2, "ERROR-2"},
+		{WarnLevel, "WARN"},
+		{WarnLevel - 1, "WARN-1"},
+		{InfoLevel, "INFO"},
+		{InfoLevel - 3, "INFO-3"},
+		{DebugLevel, "DEBUG"},
+		{InfoLevel + 2, "DEBUG+1"},
+		{-1, "!BADLEVEL(-1)"},
+	} {
+		got := test.in.String()
+		if got != test.want {
+			t.Errorf("%d: got %s, want %s", test.in, got, test.want)
+		}
+	}
+}
+
+func TestAtomicLevel(t *testing.T) {
+	var r *AtomicLevel
+	if got, want := r.Level(), Level(math.MaxInt); got != want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+	r = NewAtomicLevel(WarnLevel)
+	if got, want := r.Level(), WarnLevel; got != want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+	r.Set(InfoLevel)
+	if got, want := r.Level(), InfoLevel; got != want {
+		t.Errorf("got %v, want %v", got, want)
+	}
+
+}