docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd)

This commit is contained in:
Jakub Zych
2026-11-18 20:04:47 +01:00
parent 6409837b0c
commit cd55a3980d
9 changed files with 449 additions and 69 deletions

View File

@@ -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.