📝 Логи
Лог — первое, что открывают, когда на проде что-то сломалось. Из него понятно, какой запрос упал, у какого пользователя и на каком шаге. Хороший лог отвечает на эти вопросы за минуту, плохой превращается в гигабайты строк, по которым ничего не найти. Мониторинг упоминают в 21% вакансий Go-мидла и 10% вакансий Node.js-мидла в нашем срезе, а в одной из Go-вакансий требование сформулировано прямо: «структурированные логи из Go-сервисов». На собеседовании спрашивают, чем структурный лог лучше текстового, какие бывают уровни, как связать строки одного запроса и что нельзя писать в лог
🧠 Структурный лог
Обычная строка payment failed for order 1042: acquirer timeout удобна человеку и неудобна машине. Чтобы найти все ошибки по заказу 1042, придётся писать регулярку, и она сломается, как только кто-то поменяет формулировку
Структурный лог — это запись из полей: время, уровень, сообщение и пары ключ-значение. Чаще всего его пишут одной JSON-строкой:
{"time":"2026-11-10T16:28:41Z","level":"ERROR","msg":"payment failed","order_id":1042,"err":"acquirer timeout"}Теперь система логов фильтрует по полям: level = ERROR and order_id = 1042. Сообщение msg остаётся коротким и неизменным, вроде названия события, а всё переменное уходит в поля. Одно событие — одно постоянное сообщение, тогда по msg = "payment failed" можно посчитать, сколько раз оно случилось за час
В Go для этого есть стандартный пакет log/slog, он в стандартной библиотеке с Go 1.21. Раньше команды брали zap или zerolog, и в старых проектах ты их встретишь. Для нового кода обычно хватает slog: он даёт JSON и текстовый формат, уровни, контекст и интерфейс Handler, через который подключаются любые выходы
🎚️ Уровни
| Уровень | Число в slog | Когда писать |
|---|---|---|
Debug | -4 | Подробности для отладки: SQL-запрос, ответ внешнего API. На проде обычно выключен |
Info | 0 | Нормальные события, которые стоит видеть: сервис стартовал, заказ создан, задача выполнена |
Warn | 4 | Что-то пошло не так, но сервис справился: ретрай прошёл со второй попытки, медленный запрос |
Error | 8 | Операция не выполнилась, и на это должен кто-то посмотреть |
Уровни разнесены через 4, чтобы между ними поместились свои: в документации slog сказано, что это место под промежуточные уровни, и такой шаг совпадает с уровнями OpenTelemetry. Info равен нулю, потому что это уровень по умолчанию
Главная ошибка с уровнями — писать Error на всё подряд. Клиент прислал невалидный JSON и получил 400 — так работает валидация, хватит Info или Warn. Если Error сыплется сотнями в минуту по пустякам, настоящую ошибку в этом потоке никто не заметит. Хороший ориентир: на каждую строку Error можно ответить, кто и что должен сделать
Уровень можно менять без рестарта. slog.LevelVar безопасно менять из любой горутины, и обработчик проверяет текущее значение на каждой записи. Его выставляют, например, через админскую ручку: включили Debug на десять минут, собрали подробности, выключили
🛠️ slog на практике
Логгер создают один раз в main и передают в зависимости. К нему через With добавляют поля, общие для всех строк: имя сервиса, id запроса. Встроенные обработчики форматируют эти поля один раз, в момент вызова With
var level slog.LevelVar // по умолчанию Info
log := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: &level}))
reqLog := log.With("service", "orders", "request_id", "r-81f2")
reqLog.Info("order created", "order_id", 1042, slog.Group("user", "id", 7, "plan", "pro"))
reqLog.Debug("cache miss", "key", "order:1042") // не попадёт: уровень Info
level.Set(slog.LevelDebug) // поменяли уровень на лету
reqLog.Debug("cache miss", "key", "order:1042")Вывод на Go 1.27, первого Debug в нём нет:
{"time":"…","level":"INFO","msg":"order created","service":"orders","request_id":"r-81f2","order_id":1042,"user":{"id":7,"plan":"pro"}}
{"time":"…","level":"DEBUG","msg":"cache miss","service":"orders","request_id":"r-81f2","key":"order:1042"}Ещё три вещи, которые пригодятся в первую неделю:
slog.SetDefault(logger)делает логгер глобальным, и после этого старые вызовыlog.Printfиз сторонних пакетов тоже идут через него. В проверкеlog.Printf("old log call %d", 2)превратился в JSON-строку с"level":"INFO"AddSource: trueвHandlerOptionsдобавляет файл и строку вызова. Удобно, но каждая запись становится дороже- Ошибку передают значением:
"err", err. JSON-обработчик запишетerr.Error(), вместе с обёртками:"err":"charge: acquirer timeout"
Несколько выходов
С Go 1.26 в slog есть NewMultiHandler: он раздаёт одну запись нескольким обработчикам. Его Enabled возвращает true, если запись нужна хотя бы одному из них, а писать в итоге будут только те, кому она нужна. Типичный случай — JSON в stdout для сборщика логов и короткий текстовый вывод только ошибок в stderr
Go · Два выхода и trace_id из контекста
type ctxKey struct{}
// traceHandler достаёт trace_id из контекста и добавляет в каждую запись
type traceHandler struct{ slog.Handler }
func (h traceHandler) Handle(ctx context.Context, r slog.Record) error {
if id, ok := ctx.Value(ctxKey{}).(string); ok {
r.AddAttrs(slog.String("trace_id", id))
}
return h.Handler.Handle(ctx, r)
}
func (h traceHandler) WithAttrs(as []slog.Attr) slog.Handler {
return traceHandler{h.Handler.WithAttrs(as)}
}
func (h traceHandler) WithGroup(name string) slog.Handler {
return traceHandler{h.Handler.WithGroup(name)}
}
func main() {
jsonOut := slog.NewJSONHandler(os.Stdout, nil) // Info и выше, для сборщика логов
textErr := slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})
log := slog.New(traceHandler{slog.NewMultiHandler(jsonOut, textErr)})
ctx := context.WithValue(context.Background(), ctxKey{}, "4bf92f3577b34da6a3ce929d0e0e4736")
log.InfoContext(ctx, "payment started", "order_id", 1042)
log.ErrorContext(ctx, "payment failed", "order_id", 1042, "err", "acquirer timeout")
}В stdout ушли обе записи с trace_id, в stderr только level=ERROR msg="payment failed" … trace_id=4bf92f…. WithAttrs и WithGroup переопределены, чтобы после log.With(...) обёртка не потерялась
🔗 Как связать строки одного запроса
Запрос проходит через gateway, сервис заказов, платёжный сервис и Kafka. В каждом из них свои логи, и без общего ключа собрать историю одного запроса невозможно. Этот ключ — trace id: идентификатор, который рождается на входе и путешествует с запросом через все сервисы
По стандарту W3C Trace Context он едет в HTTP-заголовке traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01. Здесь первые 32 шестнадцатеричных символа после версии составляют trace id, следующие 16 — id текущего шага, последние два хранят флаги. Каждый сервис читает заголовок, кладёт trace id в context.Context и передаёт дальше в исходящих вызовах
Чтобы trace id попал в каждую строку лога, логируют через методы с контекстом: InfoContext, ErrorContext. Документация slog называет id текущего спана примером того, что обработчик может достать из контекста. Обёртка из примера выше делает это вручную. В проекте с OpenTelemetry трейсы, пропагацию и мост otelslog между slog и OpenTelemetry настраивают вместе, подробно об этом на странице про трейсы в этом модуле
Если трейсинга в сервисе нет, достаточно своего request_id: middleware генерирует его на входе или берёт из заголовка, кладёт в контекст и возвращает клиенту в ответе. Пользователь присылает скриншот ошибки с этим id, и ты находишь его запрос за секунды
🚚 Куда уходят логи
Сервис в контейнере пишет логи в stdout и stderr и не управляет файлами сам. Так советует «Двенадцать факторов», и так устроен Kubernetes: среда выполнения контейнеров собирает вывод, kubelet хранит его на ноде, а kubectl logs его показывает
У этого хранения жёсткие пределы, которые полезно знать до первого инцидента:
- kubelet по умолчанию ротирует файл при 10 МиБ и держит 5 файлов на контейнер, но
kubectl logsотдаёт только последний. Сервис написал 40 МиБ — увидишь не больше 10 - после рестарта контейнера остаются логи одного предыдущего запуска, их показывает
kubectl logs --previous. Это первое, что смотрят при CrashLoopBackOff - под выселили с ноды — его логи пропали вместе с ним
Поэтому на проде логи забирает агент на каждой ноде и отправляет в хранилище: Loki, Elasticsearch, ClickHouse. В той же вакансии стек назван прямо: Loki, ELK или EFK. Loki индексирует только метки, текст строк хранится без индекса, поэтому Loki дешевле Elasticsearch. Отсюда правило из его документации: в метки идут сервис, окружение, namespace, а trace id, id заказа и пользователя остаются полями внутри строки. Метка с миллионом значений раздувает индекс и тормозит запросы
🙈 Что не писать в логи
Доступ к логам обычно шире, чем к базе: их читают разработчики, поддержка, все, у кого есть Grafana. И живут они неделями. Поэтому в них не должно быть того, что OWASP советует исключать: пароли, токены доступа и id сессий, строки подключения к базе, ключи шифрования, данные карт и банковских счетов. Email, телефон и имя — персональные данные, их маскируют или не пишут вовсе
В slog для этого два механизма. LogValuer — тип сам решает, что о нём попадёт в лог. ReplaceAttr в HandlerOptions переписывает каждое поле перед выводом, и через него закрывают поля по имени:
func (u User) LogValue() slog.Value {
return slog.GroupValue(slog.Int("id", u.ID)) // email в лог не попадает
}
h := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if secretKeys[strings.ToLower(a.Key)] { // password, token, authorization
return slog.String(a.Key, "***")
}
return a
},
})
slog.New(h).Info("login", "user", User{ID: 7, Email: "anna@example.com"}, "token", "eyJhbGciOi...")
// {"time":"…","level":"INFO","msg":"login","user":{"id":7},"token":"***"}ReplaceAttr работает как страховка: поле jwt или api_key он пропустит, если его нет в списке. Надёжнее не передавать секреты в логгер вовсе. Как закрыть пароль в стартовом конфиге типом с методом String(), показано на странице про конфигурацию и graceful shutdown
⚠️ Где ошибаются
- Нечётное число аргументов.
log.Warn("slow query", "took_ms", 840, "order_id")— значение для ключа забыто, и в лог уходит"!BADKEY":"order_id".go vetловит это сам:call to slog.Logger.Warn missing a final value. Держи vet в пайплайне или пиши черезslog.Int,slog.String, где ошибиться нельзя - Дорогие аргументы на выключенном уровне. Аргументы вычисляются до проверки уровня. В проверке 1000 вызовов
log.Debug("state", "dump", expensive())при уровнеInfoвызвалиexpensive()1000 раз, хотя не записали ни строки. Тот же дамп черезLogValuerвычислился 0 раз: обработчик зовётLogValueтолько для записи, которую пишет - Одна ошибка в логе трижды. Репозиторий логирует ошибку и возвращает её, сервис логирует и возвращает, хендлер логирует ещё раз. На одну проблему три строки
Errorс разным текстом. Правило: либо обработай ошибку и запиши в лог, либо оберни черезfmt.Errorf("...: %w", err)и верни. Пишет в лог тот, кто решает, что с ней делать, обычно верхний слой - Повтор ключей. Логгер с
With("order_id", 1)и вызов с"order_id", 2дают строку{"order_id":1,"order_id":2}: встроенные обработчики дубли не убирают. jq при разборе оставит последнее значение, другой парсер может взять первое или отвергнуть строку - Лог на каждую итерацию горячего цикла. Строка
Infoна каждое сообщение из Kafka при 5000 сообщений в секунду — это 432 млн строк в сутки, и за хранение такого объёма платит компания. В горячем пути пишут агрегаты или ошибки, а поток событий видно по метрикам
🎯 Вопросы с собеседований
Чем структурный лог лучше обычного текстового?
Структурный лог состоит из полей: время, уровень, постоянное сообщение и пары ключ-значение, обычно в JSON. Система логов фильтрует и агрегирует по полям, например все ошибки по order_id = 1042, без регулярок, которые ломаются при смене формулировки. Сообщение остаётся неизменным названием события, поэтому события можно считать. В Go для этого стандартный log/slog с JSONHandler
Какие уровни логирования бывают и когда писать Error?
В slog четыре: Debug, Info, Warn, Error, с числами -4, 0, 4 и 8, между ними можно вставить свои. Debug для отладки и на проде обычно выключен, Info для нормальных событий, Warn для того, с чем сервис справился сам. Error пишу, когда операция не выполнилась и кто-то должен на это посмотреть. Ошибка клиента вроде невалидного запроса — не Error, иначе настоящие ошибки утонут в шуме
Как найти в логах все строки одного запроса, который прошёл через пять сервисов?
Нужен общий ключ, trace id. Он приходит в заголовке traceparent по стандарту W3C Trace Context или генерируется на входе, кладётся в context.Context и передаётся во все исходящие вызовы и сообщения. Логирую через InfoContext и ErrorContext, обработчик достаёт trace id из контекста и добавляет полем в каждую строку. Потом в Loki или Elasticsearch фильтрую по этому полю
Что нельзя писать в логи?
Пароли, токены, id сессий, строки подключения к базе, ключи, данные карт. Персональные данные вроде email и телефона маскируют или не пишут. В slog от этого защищают LogValuer, который решает, что из типа попадёт в лог, и ReplaceAttr, который закрывает поля по имени. Но надёжнее всего не передавать секреты в логгер, потому что список имён в ReplaceAttr всегда неполный
Почему log.Debug("x", "v", expensive()) может тормозить сервис, если Debug выключен?
Аргументы в Go вычисляются до вызова функции, поэтому expensive() выполнится, а проверка уровня внутри slog выбросит результат. Решения два: обернуть значение в тип с методом LogValue, тогда его вычислят только для записи, которую пишут, или проверить log.Enabled(ctx, slog.LevelDebug) перед вызовом
Куда сервис в Kubernetes должен писать логи и почему не в файл?
В stdout и stderr. Вывод собирает среда выполнения контейнеров, kubelet хранит его на ноде с ротацией, по умолчанию 5 файлов по 10 МиБ. Но после выселения пода логи пропадают, а kubectl logs показывает только последний файл, поэтому агент на ноде отправляет их в Loki или Elasticsearch. Файл внутри контейнера исчезнет вместе с контейнером, и его не увидит ни kubectl logs, ни агент
Почему trace id не делают меткой в Loki?
Loki индексирует только метки, и каждая уникальная комбинация меток — отдельный поток. У trace id миллионы значений, индекс раздуется, и запросы замедлятся. В метки идут поля с десятками значений: сервис, окружение, namespace. Trace id остаётся полем в строке, и по нему фильтруют внутри выбранных потоков
Ты видишь одну и ту же ошибку в логах три раза подряд с разным текстом. Что не так в коде?
Скорее всего, каждый слой логирует ошибку и возвращает её наверх: репозиторий, сервис, хендлер. Правильно либо обработать ошибку и записать в лог, либо обернуть через %w с контекстом и вернуть. Логирует тот слой, который решает, что с ошибкой делать, тогда на одну проблему одна строка с полной цепочкой обёрток
📚 Что почитать
- Structured Logging with slog — запись в блоге Go о том, зачем slog появился и как им пользоваться
- Документация log/slog — уровни,
LogValuer, раздел о производительности и примеры обработчиков - Logging Architecture — как Kubernetes хранит логи контейнеров и какие бывают схемы сбора
- OWASP Logging Cheat Sheet — что логировать для разбора инцидентов и что исключать