docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd)
This commit is contained in:
@@ -30,21 +30,34 @@ Use cases:
|
||||
|
||||
## Usage
|
||||
|
||||
A program that does not use diary installs it as the default logger:
|
||||
A program that does not use diary installs it as the default logger when it starts:
|
||||
|
||||
```go
|
||||
func main() {
|
||||
sunscreen.InstallDefault(os.Stderr)
|
||||
// ...
|
||||
```go src=modules/sunscreen/example_test.go#startLogging
|
||||
// startLogging is the first thing the main function of a program that does
|
||||
// not use diary runs; main passes os.Stderr.
|
||||
func startLogging(stderr io.Writer) {
|
||||
sunscreen.InstallDefault(stderr)
|
||||
slog.Info("starting", "token", "abc123")
|
||||
log.Print("calling the vendor with Authorization: Bearer abc.def")
|
||||
}
|
||||
```
|
||||
|
||||
To redact another handler, for example a JSON handler in a custom binary, wrap it:
|
||||
|
||||
```go
|
||||
logger := slog.New(sunscreen.Wrap(slog.NewJSONHandler(os.Stderr, nil)))
|
||||
```go src=modules/sunscreen/example_test.go#ExampleWrap_json
|
||||
// Drop the time so the output is stable; a real application keeps it.
|
||||
opts := &slog.HandlerOptions{ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
|
||||
if len(groups) == 0 && a.Key == slog.TimeKey {
|
||||
return slog.Attr{}
|
||||
}
|
||||
return a
|
||||
}}
|
||||
key, err := "live-key-123", errors.New("401 Unauthorized")
|
||||
|
||||
logger := slog.New(sunscreen.Wrap(slog.NewJSONHandler(os.Stdout, opts)))
|
||||
logger.Error("vendor call failed", "api_key", key, "err", err)
|
||||
// {"level":"ERROR","msg":"vendor call failed","api_key":"[REDACTED]","err":"..."}
|
||||
// Output:
|
||||
// {"level":"ERROR","msg":"vendor call failed","api_key":"[REDACTED]","err":"401 Unauthorized"}
|
||||
```
|
||||
|
||||
Redaction is a safety net, not a licence: log ids and outcomes, never request bodies, tokens or arguments that carry them.
|
||||
|
||||
@@ -1,9 +1,14 @@
|
||||
package sunscreen_test
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"errors"
|
||||
"io"
|
||||
"log"
|
||||
"log/slog"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/sunscreen"
|
||||
)
|
||||
@@ -28,3 +33,50 @@ func ExampleWrap() {
|
||||
// Output:
|
||||
// level=INFO msg="vendor call failed" api_key=[REDACTED] request.Authorization=[REDACTED] err="401 for key sk-[REDACTED]"
|
||||
}
|
||||
|
||||
func ExampleWrap_json() {
|
||||
// Drop the time so the output is stable; a real application keeps it.
|
||||
opts := &slog.HandlerOptions{ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
|
||||
if len(groups) == 0 && a.Key == slog.TimeKey {
|
||||
return slog.Attr{}
|
||||
}
|
||||
return a
|
||||
}}
|
||||
key, err := "live-key-123", errors.New("401 Unauthorized")
|
||||
|
||||
logger := slog.New(sunscreen.Wrap(slog.NewJSONHandler(os.Stdout, opts)))
|
||||
logger.Error("vendor call failed", "api_key", key, "err", err)
|
||||
// Output:
|
||||
// {"level":"ERROR","msg":"vendor call failed","api_key":"[REDACTED]","err":"401 Unauthorized"}
|
||||
}
|
||||
|
||||
// startLogging is the first thing the main function of a program that does
|
||||
// not use diary runs; main passes os.Stderr.
|
||||
func startLogging(stderr io.Writer) {
|
||||
sunscreen.InstallDefault(stderr)
|
||||
slog.Info("starting", "token", "abc123")
|
||||
log.Print("calling the vendor with Authorization: Bearer abc.def")
|
||||
}
|
||||
|
||||
// TestDocsInstallDefault runs startLogging into a buffer and restores the
|
||||
// process default logger and the log package afterwards.
|
||||
func TestDocsInstallDefault(t *testing.T) {
|
||||
previous, out, flags := slog.Default(), log.Writer(), log.Flags()
|
||||
t.Cleanup(func() {
|
||||
slog.SetDefault(previous)
|
||||
log.SetOutput(out)
|
||||
log.SetFlags(flags)
|
||||
})
|
||||
|
||||
var buf bytes.Buffer
|
||||
startLogging(&buf)
|
||||
got := buf.String()
|
||||
for _, want := range []string{`msg=starting token=[REDACTED]`, `Authorization: Bearer [REDACTED]`} {
|
||||
if !strings.Contains(got, want) {
|
||||
t.Errorf("output %q lacks %q", got, want)
|
||||
}
|
||||
}
|
||||
if strings.Contains(got, "abc123") || strings.Contains(got, "abc.def") {
|
||||
t.Errorf("output leaks a secret: %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user