Skip to content

Commit 779e5eb

Browse files
tjhoptjhop
committed
feat: new promslog package to wrap log/slog, deprecate promlog
Prereq for prometheus/prometheus#14355 This adds a new `promslog` package to create an opinionated slog logger for use within the prometheus ecosystem. In particular, it makes the following adjustments to normalize it to what was used in the old promlog package: - adjusts slog default timestamp key from `timestamp` -> `ts` - adjusts the timestamp value to use the same time format string ("2006-01-02T15:04:05.000Z07:00") - adjusts slog default sourcecode key from `source` -> `caller` - adjusts the formatting of the sourcecode values to trim paths with `filepath.Base()`. The formatting of the sourcecode value is similar to the go-kit/log usage, with the addition of the source function in parenthesis when debug logging is enabled. Creating a logger is similar to the old promlog package -- optionally create a `Config` struct, and then call `New()` with the config. In order to dynamically adjust the logger's level, retain the `Config` struct as it's own variable to access the `AllowedLevel.Set()` method, which internally updates the `AllowedLevel`'s slog.LevelVar to the desired log level. Ex: ```go config := &Config{} // Retain as variable to dynamically adjust log level logger := New(config) config.Level.Set("debug") logger.Debug("your message here", "hello", "world") ``` Signed-off-by: TJ Hoplock <[email protected]>
1 parent 2cac84e commit 779e5eb

File tree

3 files changed

+296
-0
lines changed

3 files changed

+296
-0
lines changed

‎promlog/log.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
// Package promlog defines standardised ways to initialize Go kit loggers
1515
// across Prometheus components.
1616
// It should typically only ever be imported by main packages.
17+
18+
// Deprecated: This package has been replaced with github.com/prometheus/common/promslog.
1719
package promlog
1820

1921
import (

‎promslog/slog.go‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
// Copyright 2024 The Prometheus Authors
2+
// Licensed under the Apache License, Version 2.0 (the "License");
3+
// you may not use this file except in compliance with the License.
4+
// You may obtain a copy of the License at
5+
//
6+
// http://www.apache.org/licenses/LICENSE-2.0
7+
//
8+
// Unless required by applicable law or agreed to in writing, software
9+
// distributed under the License is distributed on an "AS IS" BASIS,
10+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
// See the License for the specific language governing permissions and
12+
// limitations under the License.
13+
14+
// Package promslog defines standardised ways to initialize the Go standard
15+
// library's log/slog logger.
16+
// It should typically only ever be imported by main packages.
17+
package promslog
18+
19+
import (
20+
"fmt"
21+
"io"
22+
"log/slog"
23+
"os"
24+
"path/filepath"
25+
"strconv"
26+
)
27+
28+
var (
29+
LevelFlagOptions = []string{"debug", "info", "warn", "error"}
30+
FormatFlagOptions = []string{"logfmt", "json"}
31+
32+
callerAddFunc = false
33+
defaultWriter = os.Stderr
34+
replaceAttrFunc = func(groups []string, a slog.Attr) slog.Attr {
35+
key := a.Key
36+
switch key {
37+
case slog.TimeKey:
38+
a.Key = "ts"
39+
40+
// This timestamp format differs from RFC3339Nano by using .000 instead
41+
// of .999999999 which changes the timestamp from 9 variable to 3 fixed
42+
// decimals (.130 instead of .130987456).
43+
t := a.Value.Time()
44+
a.Value = slog.StringValue(t.Format("2006-01-02T15:04:05.000Z07:00"))
45+
case slog.SourceKey:
46+
a.Key = "caller"
47+
src, _ := a.Value.Any().(*slog.Source)
48+
49+
switch callerAddFunc {
50+
case true:
51+
a.Value = slog.StringValue(filepath.Base(src.File) + "(" + filepath.Base(src.Function) + "):" + strconv.Itoa(src.Line))
52+
default:
53+
a.Value = slog.StringValue(filepath.Base(src.File) + ":" + strconv.Itoa(src.Line))
54+
}
55+
default:
56+
}
57+
58+
return a
59+
}
60+
)
61+
62+
// AllowedLevel is a settable identifier for the minimum level a log entry
63+
// must be have.
64+
type AllowedLevel struct {
65+
s string
66+
lvl *slog.LevelVar
67+
}
68+
69+
func (l *AllowedLevel) UnmarshalYAML(unmarshal func(interface{}) error) error {
70+
var s string
71+
type plain string
72+
if err := unmarshal((*plain)(&s)); err != nil {
73+
return err
74+
}
75+
if s == "" {
76+
return nil
77+
}
78+
lo := &AllowedLevel{}
79+
if err := lo.Set(s); err != nil {
80+
return err
81+
}
82+
*l = *lo
83+
return nil
84+
}
85+
86+
func (l *AllowedLevel) String() string {
87+
return l.s
88+
}
89+
90+
// Set updates the value of the allowed level.
91+
func (l *AllowedLevel) Set(s string) error {
92+
if l.lvl == nil {
93+
l.lvl = &slog.LevelVar{}
94+
}
95+
96+
switch s {
97+
case "debug":
98+
l.lvl.Set(slog.LevelDebug)
99+
callerAddFunc = true
100+
case "info":
101+
l.lvl.Set(slog.LevelInfo)
102+
callerAddFunc = false
103+
case "warn":
104+
l.lvl.Set(slog.LevelWarn)
105+
callerAddFunc = false
106+
case "error":
107+
l.lvl.Set(slog.LevelError)
108+
callerAddFunc = false
109+
default:
110+
return fmt.Errorf("unrecognized log level %q", s)
111+
}
112+
l.s = s
113+
return nil
114+
}
115+
116+
// AllowedFormat is a settable identifier for the output format that the logger can have.
117+
type AllowedFormat struct {
118+
s string
119+
}
120+
121+
func (f *AllowedFormat) String() string {
122+
return f.s
123+
}
124+
125+
// Set updates the value of the allowed format.
126+
func (f *AllowedFormat) Set(s string) error {
127+
switch s {
128+
case "logfmt", "json":
129+
f.s = s
130+
default:
131+
return fmt.Errorf("unrecognized log format %q", s)
132+
}
133+
return nil
134+
}
135+
136+
// Config is a struct containing configurable settings for the logger
137+
type Config struct {
138+
Level *AllowedLevel
139+
Format *AllowedFormat
140+
ioWriter io.Writer
141+
}
142+
143+
// New returns a new slog.Logger. Each logged line will be annotated
144+
// with a timestamp. The output always goes to stderr.
145+
func New(config *Config) *slog.Logger {
146+
if config.Level == nil {
147+
config.Level = &AllowedLevel{}
148+
_ = config.Level.Set("info")
149+
}
150+
151+
if config.ioWriter == nil {
152+
config.ioWriter = defaultWriter
153+
}
154+
155+
logHandlerOpts := &slog.HandlerOptions{
156+
Level: config.Level.lvl,
157+
AddSource: true,
158+
ReplaceAttr: replaceAttrFunc,
159+
}
160+
161+
if config.Format != nil && config.Format.s == "json" {
162+
return slog.New(slog.NewJSONHandler(config.ioWriter, logHandlerOpts))
163+
}
164+
return slog.New(slog.NewTextHandler(config.ioWriter, logHandlerOpts))
165+
}

‎promslog/slog_test.go‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
// Copyright 2024 The Prometheus Authors
2+
// Licensed under the Apache License, Version 2.0 (the "License");
3+
// you may not use this file except in compliance with the License.
4+
// You may obtain a copy of the License at
5+
//
6+
// http://www.apache.org/licenses/LICENSE-2.0
7+
//
8+
// Unless required by applicable law or agreed to in writing, software
9+
// distributed under the License is distributed on an "AS IS" BASIS,
10+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
// See the License for the specific language governing permissions and
12+
// limitations under the License.
13+
14+
package promslog
15+
16+
import (
17+
"bytes"
18+
"context"
19+
"fmt"
20+
"log/slog"
21+
"regexp"
22+
"strings"
23+
"testing"
24+
25+
"github.com/stretchr/testify/require"
26+
"gopkg.in/yaml.v2"
27+
)
28+
29+
var logLevelRegexp = regexp.MustCompile(`.*level=(?P<Level>WARN|INFO|ERROR|DEBUG).*`)
30+
31+
// Make sure creating and using a logger with an empty configuration doesn't
32+
// result in a panic.
33+
func TestDefaultConfig(t *testing.T) {
34+
require.NotPanics(t, func() {
35+
logger := New(&Config{})
36+
logger.Info("empty config `Info()` test", "hello", "world")
37+
logger.Log(context.Background(), slog.LevelInfo, "empty config `Log()` test", "hello", "world")
38+
logger.LogAttrs(context.Background(), slog.LevelInfo, "empty config `LogAttrs()` test", slog.String("hello", "world"))
39+
})
40+
}
41+
42+
func TestUnmarshallLevel(t *testing.T) {
43+
l := &AllowedLevel{}
44+
err := yaml.Unmarshal([]byte(`debug`), l)
45+
if err != nil {
46+
t.Error(err)
47+
}
48+
if l.s != "debug" {
49+
t.Errorf("expected %s, got %s", "debug", l.s)
50+
}
51+
}
52+
53+
func TestUnmarshallEmptyLevel(t *testing.T) {
54+
l := &AllowedLevel{}
55+
err := yaml.Unmarshal([]byte(``), l)
56+
if err != nil {
57+
t.Error(err)
58+
}
59+
if l.s != "" {
60+
t.Errorf("expected empty level, got %s", l.s)
61+
}
62+
}
63+
64+
func TestUnmarshallBadLevel(t *testing.T) {
65+
l := &AllowedLevel{}
66+
err := yaml.Unmarshal([]byte(`debugg`), l)
67+
if err == nil {
68+
t.Error("expected error")
69+
}
70+
expErr := `unrecognized log level "debugg"`
71+
if err.Error() != expErr {
72+
t.Errorf("expected error %s, got %s", expErr, err.Error())
73+
}
74+
if l.s != "" {
75+
t.Errorf("expected empty level, got %s", l.s)
76+
}
77+
}
78+
79+
func getLogEntryLevelCounts(s string) map[string]int {
80+
counters := make(map[string]int)
81+
lines := strings.Split(s, "\n")
82+
for _, line := range lines {
83+
matches := logLevelRegexp.FindStringSubmatch(line)
84+
if len(matches) > 1 {
85+
levelIndex := logLevelRegexp.SubexpIndex("Level")
86+
87+
counters[matches[levelIndex]]++
88+
}
89+
}
90+
91+
return counters
92+
}
93+
94+
func TestDynamicLevels(t *testing.T) {
95+
var buf bytes.Buffer
96+
config := &Config{ioWriter: &buf}
97+
logger := New(config)
98+
99+
// Test that log level can be adjusted on-the-fly to debug and that a
100+
// log entry can be written to the file.
101+
if err := config.Level.Set("debug"); err != nil {
102+
t.Fatal(err)
103+
}
104+
logger.Info("info", "hello", "world")
105+
logger.Debug("debug", "hello", "world")
106+
107+
counts := getLogEntryLevelCounts(buf.String())
108+
require.Equal(t, 1, counts["INFO"], "info log successfully detected")
109+
require.Equal(t, 1, counts["DEBUG"], "debug log successfully detected")
110+
// Print logs for humans to see, if needed.
111+
fmt.Println(buf.String())
112+
buf.Reset()
113+
114+
// Test that log level can be adjusted on-the-fly to info and that a
115+
// subsequent call to write a debug level log is _not_ written to the
116+
// file.
117+
if err := config.Level.Set("info"); err != nil {
118+
t.Fatal(err)
119+
}
120+
logger.Info("info", "hello", "world")
121+
logger.Debug("debug", "hello", "world")
122+
123+
counts = getLogEntryLevelCounts(buf.String())
124+
require.Equal(t, 1, counts["INFO"], "info log successfully detected")
125+
require.NotEqual(t, 1, counts["DEBUG"], "extra debug log detected")
126+
// Print logs for humans to see, if needed.
127+
fmt.Println(buf.String())
128+
buf.Reset()
129+
}

0 commit comments

Comments
 (0)