119 lines
3.5 KiB
Markdown
119 lines
3.5 KiB
Markdown
# splinter
|
|
|
|
Simple and minimal logger in Go for my projects.
|
|
|
|
Fans out structured records to one or more streams. Ships with a console
|
|
stream (JSON or pretty text) and a file stream with size- and time-based
|
|
rotation, optional gzip compression, and backup pruning.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
go get git.juancwu.dev/juancwu/splinter@v0.1.0
|
|
```
|
|
|
|
Requires Go 1.26 or newer.
|
|
|
|
## Quick start
|
|
|
|
The package exposes a default logger that writes JSON to stderr at
|
|
`LevelInfo`:
|
|
|
|
```go
|
|
package main
|
|
|
|
import "git.juancwu.dev/juancwu/splinter"
|
|
|
|
func main() {
|
|
splinter.Info("server started", "port", 8080)
|
|
splinter.Error("request failed", "err", "timeout")
|
|
}
|
|
```
|
|
|
|
## Custom logger with file output and rotation
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"time"
|
|
|
|
"git.juancwu.dev/juancwu/splinter"
|
|
)
|
|
|
|
func main() {
|
|
logger := splinter.New(
|
|
splinter.WithStream(splinter.NewConsoleStream(
|
|
splinter.ConsolePretty, splinter.LevelDebug,
|
|
)),
|
|
splinter.WithStream(splinter.MustFileStream("logs/app.log", splinter.FileStreamConfig{
|
|
Level: splinter.LevelInfo,
|
|
Format: splinter.FileJSON,
|
|
MaxSizeMB: 100, // rotate at 100 MB
|
|
MaxAge: 24 * time.Hour, // and at least once per day
|
|
MaxBackups: 7, // keep the 7 most recent files
|
|
Compress: true, // gzip rotated backups
|
|
})),
|
|
splinter.WithAttrs(map[string]any{"service": "api"}),
|
|
)
|
|
defer logger.Close()
|
|
|
|
splinter.SetDefault(logger)
|
|
|
|
splinter.Info("ready")
|
|
}
|
|
```
|
|
|
|
## Child loggers
|
|
|
|
`Logger.With` returns a child that inherits streams and merges additional
|
|
attributes onto every record:
|
|
|
|
```go
|
|
req := logger.With(map[string]any{"request_id": id})
|
|
req.Info("handled", "status", 200)
|
|
```
|
|
|
|
## Custom streams
|
|
|
|
Implement the `Stream` interface to send logs anywhere — a database, a
|
|
message queue, an HTTP endpoint, an in-memory buffer for tests:
|
|
|
|
```go
|
|
type Stream interface {
|
|
Name() string
|
|
Write(ctx context.Context, rec splinter.Record) error
|
|
Enabled(level splinter.Level) bool
|
|
Close() error
|
|
}
|
|
```
|
|
|
|
Add it with `splinter.WithStream(myStream)` at construction time.
|
|
|
|
## Configuration reference
|
|
|
|
### `ConsoleStream`
|
|
|
|
| Constructor | Behaviour |
|
|
| ----------------------------------------- | -------------------------------------- |
|
|
| `NewConsoleStream(ConsoleJSON, level)` | One JSON object per line on stderr. |
|
|
| `NewConsoleStream(ConsolePretty, level)` | `key=value` text on stderr. |
|
|
| `ConsoleWriter(w)` option | Override the destination writer. |
|
|
|
|
### `FileStream`
|
|
|
|
| Field | Default | Notes |
|
|
| ------------ | ----------- | -------------------------------------------------------------- |
|
|
| `Level` | `LevelInfo` | Minimum level written to the file. |
|
|
| `Format` | `FileJSON` | `FileJSON` or `FileText`. |
|
|
| `MaxSizeMB` | `100` | Rotation threshold in MB. `0` disables size-based rotation. |
|
|
| `MaxAge` | `0` | Rotation threshold by age. `0` disables time-based rotation. |
|
|
| `MaxBackups` | `5` | Number of rotated files to retain (raw + `.gz` combined). |
|
|
| `Compress` | `false` | gzip rotated files asynchronously after rename. |
|
|
|
|
When both `MaxSizeMB` and `MaxAge` are zero, `MaxSizeMB` defaults to `100`
|
|
to prevent unbounded growth.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|