SNekLog/README.md

SNekLog (ScuroNeko Logger)

Small structured logger for Go with text and JSON output, multiple writers, and optional traceback metadata.

Russian version: 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

go get git.scuroneko.dev/scuroneko/slog/v2

Quick start

package main

import (
	"log"

	"git.scuroneko.dev/scuroneko/slog/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:

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:

{
  "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.

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 slog frames and runtime frames are filtered out.

Repository example

See examples/main.go.

License

This project is licensed under GNU GPLv3. See LICENSE.