docs: add godoc and bilingual README

2026-03-17 15:33:11 +03:00
parent 6112a707c7
commit badee2c598
10 changed files with 541 additions and 54 deletions
--- a/README_ru.md
+++ b/README_ru.md
@@ -0,0 +1,138 @@
+# slog
+
+Небольшой структурированный логгер для Go с текстовым и JSON-выводом, несколькими writer'ами и настраиваемыми traceback-метаданными.
+
+English version: [README.md](README.md)
+
+## Возможности
+
+- Одновременная запись в несколько destinations.
+- Текстовый и JSON-форматы.
+- `stdout`, файлы и любые внешние `io.Writer`.
+- Опциональные timestamp'ы для текстового вывода.
+- Компактный traceback для текстовых writer'ов и полный traceback для JSON.
+- Явные правила владения writer'ами при `Close()`.
+
+## Установка
+
+```bash
+go get git.nix13.pw/scuroneko/slog
+```
+
+## Быстрый старт
+
+```go
+package main
+
+import (
+	"log"
+
+	"git.nix13.pw/scuroneko/slog"
+)
+
+func main() {
+	logger := slog.CreateLogger().
+		Prefix("API").
+		Level(slog.DEBUG).
+		PrintTraceback(true).
+		JsonPretty(true)
+
+	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")
+
+	if err := logger.Close(); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+## Значения по умолчанию
+
+`CreateLogger()` создает логгер со следующими настройками:
+
+- `Prefix("LOG")`
+- `Level(slog.FATAL)`
+- `PrintTime(true)`
+- `PrintTraceback(false)`
+- `JsonPretty(false)`
+
+Важно: в текущей модели уровней `Level(slog.FATAL)` пропускает `INFO`, `WARN`, `ERROR` и `FATAL`, но не `DEBUG`. Чтобы включить все сообщения, используйте `Level(slog.DEBUG)`.
+
+## Writer'ы и владение
+
+`Logger.Close()` закрывает только writer'ы, которые логгер создал сам:
+
+- `CreateTextFileWriter(...)`
+- `CreateJsonFileWriter(...)`
+
+Внешние writer'ы не закрываются:
+
+- `CreateTextWriter(existingWriter)`
+- `CreateJsonWriter(existingWriter)`
+- `CreateTextStdoutWriter()`
+- `CreateJsonStdoutWriter()`
+
+Это позволяет безопасно подключать `bytes.Buffer`, сетевые writer'ы и другие уже управляемые ресурсы.
+
+## Форматы вывода
+
+Текстовый writer формирует записи вида:
+
+```text
+[API] [INFO] [main.go:main:27] [17.03.26 14:05:09] service started
+```
+
+Поле traceback появляется только если включен `PrintTraceback(true)`.
+
+JSON writer записывает объект со следующими полями:
+
+```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"
+    }
+  ]
+}
+```
+
+Если включен `JsonPretty(true)`, JSON выводится с отступами.
+
+## API кратко
+
+- `Info`, `Warn`, `Error`, `Debug`, `Fatal` принимают список значений.
+- `Infof`, `Warnf`, `Errorf`, `Debugf`, `Fatalf` используют `fmt.Sprintf`.
+- Методы `*ln` добавляют семантику перевода строки, что удобно для `stdout`, Docker и line-based collectors.
+- `Fatal`, `Fatalf` и `Fatalln` вызывают `os.Exit(1)` после записи сообщения.
+
+## Поведение traceback
+
+- Текстовые writer'ы используют ближайший пользовательский stack frame.
+- JSON writer'ы получают полный traceback.
+- Внутренние frame'ы `slog` и `runtime` фильтруются из traceback.
+
+## Пример из репозитория
+
+См. [examples/main.go](examples/main.go).
+
+## Лицензия
+
+Проект распространяется под GNU GPLv3. См. [LICENSE](LICENSE).