mirror of
https://codeberg.org/scip/yadu.git
synced 2025-12-16 20:21:00 +01:00
Thomas von Dein
a6b112cfcb
- added unit tests - renamed to yadu - added gh test actions - added docs
132 lines
3.4 KiB
Markdown
132 lines
3.4 KiB
Markdown
[](https://goreportcard.com/report/github.com/tlinden/yadu)
|
|
[](https://github.com/tlinden/yadu/actions)
|
|
[](https://raw.githack.com/wiki/tlinden/yadu/coverage.html)
|
|
|
|
|
|
# yadu - a human readable yaml based slog.Handler
|
|
|
|
## Introduction
|
|
|
|
Package yadu provides a handler for the log/slog logging framework.
|
|
|
|
It generates a mixture of text lines containing the timestamp and
|
|
log message and a YAML dump of the provided attibutes.
|
|
|
|
## Log format
|
|
|
|
The log format generated by yadu looks like this:
|
|
|
|
```
|
|
2023-04-02T10:50.09 EDT LEVEL Message text
|
|
foo: value
|
|
bar: 12345
|
|
```
|
|
|
|
## Example
|
|
|
|
```go
|
|
logger := slog.New(yadu.NewHandler(os.Stdout, nil))
|
|
|
|
type Enemy struct {
|
|
Alive bool
|
|
Health int
|
|
Name string
|
|
Body body `yaml:"-"` // not printed
|
|
Ammo []Ammo
|
|
}
|
|
|
|
e := &Enemy{Alive: true, Health: 10, Name: "Bodo", Body: "body\nbody\n",
|
|
Ammo: []Ammo{{Forweapon: "Railgun", Range: 400, Impact: 100, Cost: 100000}},
|
|
}
|
|
|
|
slog.Info("info", "enemy", e, "spawn", 199)
|
|
```
|
|
|
|
Output:
|
|
|
|
```sh
|
|
2024-01-18T02:57.41 CET INFO: info
|
|
enemy:
|
|
alive: true
|
|
health: 10
|
|
name: Bodo
|
|
ammo:
|
|
- forweapon: Railgun
|
|
impact: 100
|
|
cost: 100000
|
|
range: 400
|
|
spawn: 199
|
|
```
|
|
|
|
See `example/example.go` for usage.
|
|
|
|
## Installation
|
|
|
|
Execute this to add the module to your project:
|
|
```sh
|
|
go get github.com/tlinden/yadu
|
|
```
|
|
|
|
## Configuration
|
|
|
|
You can tweak the behavior of the handler as any other handler by using the Options struct:
|
|
|
|
```go
|
|
func removeTime(_ []string, a slog.Attr) slog.Attr {
|
|
if a.Key == slog.TimeKey {
|
|
return slog.Attr{}
|
|
}
|
|
return a
|
|
}
|
|
|
|
opts := &yadu.Options{
|
|
Level: slog.LevelDebug,
|
|
ReplaceAttr: removeTime,
|
|
}
|
|
```
|
|
|
|
Pass this object to `yadu.NewHandler()`.
|
|
|
|
Because you can pass whole structs to the logger which will be dumped
|
|
using YAML, there's also a way to exclude fields from being printed:
|
|
|
|
```go
|
|
type User struct {
|
|
Id int
|
|
User string
|
|
Pass string `yaml:"-"`
|
|
}
|
|
```
|
|
|
|
If you're already using YAML tags for other purposes you can also just
|
|
add a `LogValue()` method to your struct, which will be called by
|
|
slog. Refer to the slog documentation how to use it.
|
|
|
|
You can also modify the time format using `yadu.Options.TimeFormat`.
|
|
|
|
## Acknowledgements
|
|
|
|
I wrote most of the code with the help of the [humane slog
|
|
handler][humane]. Also helpfull was the [guide to writing `slog` handlers][guide].
|
|
|
|
+ [humane slog handler][humane]
|
|
+ [A Guide to Writing `slog` Handlers][guide]
|
|
+ [`slog`: Golang's official structured logging package][sobyte]
|
|
+ [A Comprehensive Guide to Structured Logging in Go][betterstack]
|
|
|
|
[humane]: https://github.com/telemachus/humane/tree/main
|
|
[guide]: https://github.com/golang/example/tree/master/slog-handler-guide
|
|
[mrkaran]: https://mrkaran.dev/posts/structured-logging-in-go-with-slog/
|
|
[betterstack]: https://betterstack.com/community/guides/logging/logging-in-go/
|
|
|
|
|
|
## LICENSE
|
|
|
|
This module is published under the terms of the BSD 3-Clause
|
|
License. Please read the file LICENSE for details.
|
|
|
|
## Author
|
|
|
|
Thomas von Dein `<git |AT| daemon.de>`
|
|
|