К содержимому
Войти

Python Road Map

📝 Логи

Лог — первое, что открывают, когда на проде что-то сломалось. Из него понятно, какой запрос упал, у какого пользователя и на каком шаге. Хороший лог отвечает на эти вопросы за минуту, плохой превращается в гигабайты строк, по которым ничего не найти. Мониторинг упоминают в 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. На проде обычно выключен
Info0Нормальные события, которые стоит видеть: сервис стартовал, заказ создан, задача выполнена
Warn4Что-то пошло не так, но сервис справился: ретрай прошёл со второй попытки, медленный запрос
Error8Операция не выполнилась, и на это должен кто-то посмотреть

Уровни разнесены через 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 — что логировать для разбора инцидентов и что исключать