FILE / ScuroNeko/SNekLog
README.md
Исходный файл и его история в репозитории.
159 lines
4.0 KiB
Markdown
159 lines
4.0 KiB
Markdown
# SNekLog (ScuroNeko Logger)
|
|
|
|
Small structured logger for Go with text and JSON output, multiple writers, and optional traceback metadata.
|
|
|
|
Russian version: [README_ru.md](README_ru.md)
|
|
|
|
## Features
|
|
|
|
- Fan out the same record to multiple destinations.
|
|
- Text and JSON writers.
|
|
- `stdout`, files, and arbitrary external `io.Writer` values.
|
|
- Optional timestamps for text output.
|
|
- Compact traceback metadata for text writers and full traceback slices for JSON.
|
|
- Message replacement for masking secrets or normalizing output.
|
|
- Explicit ownership rules for writer closing.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get git.scuroneko.dev/scuroneko/sneklog/v2
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"log"
|
|
|
|
"git.scuroneko.dev/scuroneko/sneklog/v2"
|
|
)
|
|
|
|
func main() {
|
|
logger := sneklog.CreateLogger().
|
|
Prefix("API").
|
|
Level(sneklog.DEBUG).
|
|
AddReplacer("SOME_SECRET", "<redacted>")
|
|
|
|
text := logger.CreateTextStdoutWriter()
|
|
jsonFile, err := logger.CreateJsonFileWriter("logs/app.json")
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
logger.AddWriters(text, jsonFile)
|
|
|
|
logger.Infoln("service started")
|
|
logger.Warnln("cache miss")
|
|
logger.Errorln("request failed")
|
|
logger.Debugln("debug details")
|
|
logger.Infoln("token", "SOME_SECRET")
|
|
|
|
if err := logger.Close(); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Defaults
|
|
|
|
`CreateLogger()` starts with:
|
|
|
|
- `Prefix("LOG")`
|
|
- `Level(sneklog.FATAL)`
|
|
- `JsonPretty(false)`
|
|
- text formatter: `sneklog.DefaultTextFormatter`
|
|
- JSON formatter: `sneklog.DefaultJsonFormatter`
|
|
|
|
Important: with the current level ordering, `Level(sneklog.FATAL)` allows `INFO`, `WARN`, `ERROR`, and `FATAL`, but not `DEBUG`. Use `Level(sneklog.DEBUG)` to enable every level.
|
|
|
|
## Writers and ownership
|
|
|
|
`Logger.Close()` only closes writers created by the logger itself:
|
|
|
|
- `CreateTextFileWriter(...)`
|
|
- `CreateJsonFileWriter(...)`
|
|
|
|
The following writers remain owned by the caller and are not closed by `Logger.Close()`:
|
|
|
|
- `CreateTextWriter(existingWriter)`
|
|
- `CreateJsonWriter(existingWriter)`
|
|
- `CreateTextStdoutWriter()`
|
|
- `CreateJsonStdoutWriter()`
|
|
|
|
This makes it safe to plug in `bytes.Buffer`, network writers, and other externally managed resources.
|
|
|
|
## Output formats
|
|
|
|
Text writers render records like:
|
|
|
|
```text
|
|
2026-03-17T14:05:09+03:00 info API: service started
|
|
```
|
|
|
|
Use `SetFormatter` on a writer to customize timestamps, traceback fields, colors, and message layout.
|
|
|
|
JSON writers emit objects with this shape:
|
|
|
|
```json
|
|
{
|
|
"time": "2026-03-17T14:05:09.123456789+03:00",
|
|
"level": "info",
|
|
"prefix": "API",
|
|
"message": "service started",
|
|
"traceback": [
|
|
{
|
|
"method": "main",
|
|
"filename": "main.go",
|
|
"line": 27,
|
|
"signature": "main.main",
|
|
"fullPath": "/path/to/main.go"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
When `JsonPretty(true)` is enabled, JSON is indented.
|
|
|
|
## Message replacement
|
|
|
|
`AddReplacer(old, new)` replaces matching text in every message before the
|
|
record reaches any writer. Replacement rules are applied in the order they are
|
|
added.
|
|
|
|
```go
|
|
logger := sneklog.CreateLogger().
|
|
Level(sneklog.DEBUG).
|
|
AddReplacer("SOME_SECRET", "<redacted>").
|
|
AddReplacer("user@example.com", "<email>")
|
|
|
|
logger.Infoln("login token:", "SOME_SECRET")
|
|
```
|
|
|
|
This writes `<redacted>` instead of `SOME_SECRET` in both text and JSON output.
|
|
An empty `old` value is ignored.
|
|
|
|
## API summary
|
|
|
|
- `Info`, `Warn`, `Error`, `Debug`, and `Fatal` accept a list of values.
|
|
- `Infof`, `Warnf`, `Errorf`, `Debugf`, and `Fatalf` use `fmt.Sprintf`.
|
|
- The `*ln` methods preserve newline semantics, which is useful for `stdout`, Docker, and line-based collectors.
|
|
- `Fatal`, `Fatalf`, and `Fatalln` call `os.Exit(1)` after writing the message.
|
|
- `AddReplacer` masks or rewrites message text before records are sent to writers.
|
|
|
|
## Traceback behavior
|
|
|
|
- Text writers use the nearest user stack frame.
|
|
- JSON writers receive the full traceback slice.
|
|
- Internal `sneklog` frames and `runtime` frames are filtered out.
|
|
|
|
## Repository example
|
|
|
|
See [examples/main.go](examples/main.go).
|
|
|
|
## License
|
|
|
|
This project is licensed under GNU GPLv3. See [LICENSE](LICENSE).
|