restructured logger from budigt

README.md

@@ -1,3 +1,119 @@
 # splinter
 
-Simple and minimal logger in Go for my projects.
+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
+```
+
+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).