Структурированное логирование с slog

Структурированное логирование с slog

С Go 1.21 в stdlib появился log/slog - структурированное логирование из коробки. Раньше команды выбирали между logrus, zap, zerolog; теперь у всех есть единый стандартный API.

Три столпа observability: logs, metrics, traces связаны через trace_id

Почему не fmt.Println

// ПЛОХО: парсить grep-ом, не агрегировать
fmt.Printf("User %s logged in from %s\n", userID, ip)

// ХОРОШО: ключ-значение → JSON → индексируется
slog.Info("user logged in", "user_id", userID, "ip", ip)
// {"time":"...","level":"INFO","msg":"user logged in","user_id":"123","ip":"192.168.1.1"}
<?php
declare(strict_types=1);

use Psr\Log\LoggerInterface;

final class LoginService
{
    public function __construct(private readonly LoggerInterface $logger) {}

    public function handle(string $userId, string $ip): void
    {
        // ПЛОХО: строковая конкатенация, ничего не агрегировать
        $this->logger->info('User ' . $userId . ' logged in from ' . $ip);

        // ХОРОШО: контекст - массив; Monolog JsonFormatter сериализует в JSON
        $this->logger->info('user logged in', [
            'user_id' => $userId,
            'ip' => $ip,
        ]);
    }
}

В PHP стандарт - PSR-3 (Psr\Log\LoggerInterface), индустриальная реализация - Monolog. В Symfony логгер инжектится через DI (MonologBundle).

import logging

# stdlib logging - стандарт де-факто; структурные поля передаются через extra,
# в JSON их превращает Formatter (свой, python-json-logger или structlog)
logger = logging.getLogger(__name__)

# ПЛОХО: парсить grep-ом, не агрегировать
print(f"User {user_id} logged in from {ip}")

# ХОРОШО: ключ-значение через extra -> JSON-Formatter делает из них поля -> индексируется
logger.info("user logged in", extra={"user_id": user_id, "ip": ip})
# {"time":"...","level":"INFO","msg":"user logged in","user_id":"123","ip":"192.168.1.1"}

В продакшене логи попадают в систему агрегации (Loki, Elasticsearch, CloudWatch). Структурированный вывод позволяет искать по полям: user_id="123", фильтровать по level, строить графики ошибок по сервисам.

Уровни логирования

slog.Debug("detailed info")    // отключён в проде по умолчанию
slog.Info("normal operation")  // штатные события: запросы, фоновые задачи
slog.Warn("something unusual") // деградация, retry, fallback
slog.Error("failed", "err", err) // требует внимания, но не падение
<?php
declare(strict_types=1);

use Psr\Log\LoggerInterface;

final class OrderProcessor
{
    public function __construct(private readonly LoggerInterface $logger) {}

    public function process(int $orderId, ?Throwable $err = null): void
    {
        $this->logger->debug('detailed info', ['order_id' => $orderId]);
        $this->logger->info('normal operation', ['order_id' => $orderId]);
        $this->logger->warning('something unusual', ['order_id' => $orderId]);

        if ($err !== null) {
            $this->logger->error('failed', [
                'order_id' => $orderId,
                'exception' => $err,
            ]);
        }
    }
}

PSR-3 определяет восемь уровней (RFC 5424): debug, info, notice, warning, error, critical, alert, emergency. На практике хватает debug/info/warning/error.

import logging

logger = logging.getLogger(__name__)

logger.debug("detailed info")        # отключён в проде по умолчанию (root = WARNING, ставят INFO)
logger.info("normal operation")      # штатные события: запросы, фоновые задачи
logger.warning("something unusual")  # деградация, retry, fallback
logger.error("failed", exc_info=err) # требует внимания, но не падение; exc_info добавит traceback

# Пятый уровень CRITICAL - для невосстановимых ситуаций перед остановкой процесса

Правило: DEBUG для разработки, INFO для бизнес-событий, WARN для аномалий, ERROR для проблем. Если на каждый ERROR никто не среагирует - это WARN.

Настройка JSON-handler

opts := &slog.HandlerOptions{
    Level:     slog.LevelInfo,
    AddSource: true, // добавляет file:line - полезно при поиске
}
handler := slog.NewJSONHandler(os.Stdout, opts)
slog.SetDefault(slog.New(handler))
<?php
declare(strict_types=1);

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\JsonFormatter;
use Monolog\Processor\IntrospectionProcessor;

$handler = new StreamHandler('php://stdout', Logger::INFO);
$handler->setFormatter(new JsonFormatter());

$logger = new Logger('app');
$logger->pushHandler($handler);
// IntrospectionProcessor добавляет file/line/class - аналог AddSource: true
$logger->pushProcessor(new IntrospectionProcessor(Logger::DEBUG));

В Monolog handler-ы пишут в разные приёмники (StreamHandler, SyslogHandler, RotatingFileHandler), а formatters задают формат. Для прода - JsonFormatter, для CLI разработки - LineFormatter.

В Symfony это настраивается декларативно в config/packages/monolog.yaml: каналы, handler-ы, форматтеры. Контроллеры и сервисы получают LoggerInterface через autowiring.

import json
import logging
import sys
from datetime import datetime, timezone


class JsonFormatter(logging.Formatter):
    """В stdlib нет JSON-форматтера - пишем свой.
    Альтернативы без ручной работы: python-json-logger или structlog."""

    # Стандартные поля LogRecord - их не дублируем как пользовательские атрибуты
    _RESERVED = set(vars(logging.makeLogRecord({}))) | {"message", "asctime"}

    def format(self, record: logging.LogRecord) -> str:
        entry: dict[str, object] = {
            "time": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
            "level": record.levelname,
            "msg": record.getMessage(),
            # аналог AddSource: true - file:line полезны при поиске
            "source": f"{record.pathname}:{record.lineno}",
        }
        # Всё, что пришло через extra={...}, становится полями JSON
        for key, value in vars(record).items():
            if key not in self._RESERVED:
                entry[key] = value
        if record.exc_info:
            entry["exc_info"] = self.formatException(record.exc_info)
        return json.dumps(entry, ensure_ascii=False, default=str)


handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
# force=True: если root-логгер уже настроен (предыдущим basicConfig или
# библиотекой), без него повторный basicConfig молча ничего не делает
logging.basicConfig(level=logging.INFO, handlers=[handler], force=True)

В stdlib handler-ы тоже пишут в разные приёмники (StreamHandler, RotatingFileHandler, SysLogHandler, QueueHandler), formatter задаёт формат. В Django и других фреймворках то же самое конфигурируется декларативно через logging.config.dictConfig.

Контекстные поля через With

logger := slog.Default().With(
    "service", "user-api",
    "version", "1.2.3",
)
logger.Info("request",
    "method", "GET",
    "path", "/users",
    "status", 200,
    "duration_ms", 42,
)
<?php
declare(strict_types=1);

use Monolog\Logger;
use Monolog\LogRecord;

$logger = (new Logger('user-api'))->withName('user-api');
$logger->pushProcessor(static function (LogRecord $record): LogRecord {
    $record->extra['service'] = 'user-api';
    $record->extra['version'] = '1.2.3';
    return $record;
});

$logger->info('request', [
    'method' => 'GET',
    'path' => '/users',
    'status' => 200,
    'duration_ms' => 42,
]);

В Monolog аналог - Logger::withName() плюс processor, который добавляет статические поля ко всем записям. Каждая запись получает их без дублирования в info().

import logging


class ContextAdapter(logging.LoggerAdapter):
    # Аналог With: адаптер приклеивает свои поля к каждой записи.
    # Стандартный LoggerAdapter затирает extra вызова своим словарём
    # (merge_extra=True появился только в 3.13) - переопределяем process
    def process(self, msg: str, kwargs: dict) -> tuple[str, dict]:
        kwargs["extra"] = {**self.extra, **kwargs.get("extra", {})}
        return msg, kwargs


logger = ContextAdapter(
    logging.getLogger("app"),
    {"service": "user-api", "version": "1.2.3"},
)
logger.info(
    "request",
    extra={"method": "GET", "path": "/users", "status": 200, "duration_ms": 42},
)

Processor создаёт новый logger со «прилипшими» полями - это дешевле, чем дублировать их в каждом вызове. В Go удобно прокидывать через context.WithValue, чтобы handler-ы и сервисы логировали с одинаковыми атрибутами; в PHP роль ctx играет request-scope DI-контейнер.

Correlation ID (request ID)

Один HTTP-запрос порождает десятки логов: middleware, handler, сервис, репозиторий. Correlation ID связывает их вместе.

Correlation ID проходит через middleware, handler, service, repository и попадает в каждый лог

type ctxKey string
const correlationKey ctxKey = "correlation_id"

func correlationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Correlation-ID")
        if id == "" {
            id = uuid.New().String()
        }
        ctx := context.WithValue(r.Context(), correlationKey, id)
        w.Header().Set("X-Correlation-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// В handler-ах
func loggerFromCtx(ctx context.Context) *slog.Logger {
    if id, ok := ctx.Value(correlationKey).(string); ok {
        return slog.Default().With("correlation_id", id)
    }
    return slog.Default()
}
<?php
declare(strict_types=1);

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Uid\Uuid;
use Monolog\LogRecord;

final class CorrelationIdSubscriber implements EventSubscriberInterface
{
    public function __construct(private CorrelationIdHolder $holder) {}

    public static function getSubscribedEvents(): array
    {
        return [KernelEvents::REQUEST => ['onRequest', 250]];
    }

    public function onRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $id = $request->headers->get('X-Correlation-ID') ?? Uuid::v4()->toRfc4122();
        $this->holder->set($id);
        $request->attributes->set('correlation_id', $id);
    }
}

// Monolog processor читает значение из holder-а
final class CorrelationIdProcessor
{
    public function __construct(private readonly CorrelationIdHolder $holder) {}

    public function __invoke(LogRecord $record): LogRecord
    {
        $record->extra['correlation_id'] = $this->holder->get();
        return $record;
    }
}

В Symfony correlation_id ставит EventSubscriber на kernel.request, а Monolog processor добавляет его ко всем записям. PHP не имеет ctx-объекта, как Go: значение хранится в обычном shared-сервисе-holder-е (как CorrelationIdHolder выше) или в request attributes. Scopes в Symfony DI удалены ещё в 3.0; в долгоживущих рантаймах (RoadRunner, FrankenPHP worker) holder сбрасывают между запросами через ResetInterface.

import logging
import uuid
from contextvars import ContextVar
from typing import Any, Callable, Iterable

WSGIApp = Callable[[dict[str, Any], Callable[..., Any]], Iterable[bytes]]

# Аналог context.WithValue: ContextVar изолирован на поток / asyncio-задачу,
# явно прокидывать его через аргументы не нужно
correlation_id: ContextVar[str] = ContextVar("correlation_id", default="")


def correlation_middleware(app: WSGIApp) -> WSGIApp:
    # WSGI-обёртка; в FastAPI это @app.middleware("http"), в Django - класс в MIDDLEWARE
    def wrapper(environ: dict[str, Any], start_response: Callable[..., Any]) -> Iterable[bytes]:
        request_id = environ.get("HTTP_X_CORRELATION_ID") or str(uuid.uuid4())
        token = correlation_id.set(request_id)

        def start_with_header(status: str, headers: list[tuple[str, str]], exc_info: Any = None) -> Any:
            return start_response(status, [*headers, ("X-Correlation-ID", request_id)], exc_info)

        try:
            return app(environ, start_with_header)
        finally:
            correlation_id.reset(token)

    return wrapper


# В handler-ах (ContextAdapter - из раздела про контекстные поля)
def logger_from_ctx() -> logging.LoggerAdapter:
    if request_id := correlation_id.get():
        return ContextAdapter(logging.getLogger("app"), {"correlation_id": request_id})
    return ContextAdapter(logging.getLogger("app"), {})

Если запрос проходит через несколько микросервисов, header X-Correlation-ID пробрасывается дальше - так correlation ID связывает логи всех сервисов. При наличии трейсинга ту же роль играет trace_id из заголовка traceparent (W3C Trace Context) - это отдельный идентификатор, о нём ниже.

Агрегация: Loki vs ELK

Куда складывать логи в проде:

  • Grafana Loki - индексирует только labels, тело лога хранится сжатым. Дёшево по памяти и диску. Хорошо для большого объёма низкочастотных запросов.
  • Elasticsearch (ELK) - полнотекстовый индекс по всем полям. Дороже, но мощный поиск и аналитика. Подходит для security-аудита, форензики.
  • CloudWatch / Stackdriver - managed-сервисы облаков. Удобно, но дороже на больших объёмах.
# docker-compose: Loki + Grafana Alloy (агент, который читает логи и шлёт их в Loki)
# Версии закреплены, чтобы пример воспроизводился; берите актуальные со страниц релизов
services:
  loki:
    image: grafana/loki:3.3.2
    ports: ["3100:3100"]
  alloy:
    image: grafana/alloy:v1.5.1
    volumes:
      - /var/log:/var/log
      - ./config.alloy:/etc/alloy/config.alloy

Раньше эту роль играл Promtail, но Grafana объявила его устаревшим (поддержка заканчивается в 2026) и рекомендует Alloy. В старых статьях и конфигах Promtail ещё встретится часто.

Что логировать и что НЕ логировать

✅ Логируй:

  • Входящие запросы: метод, путь, статус, длительность, user_id
  • Ошибки: с контекстом (что пытались сделать, какой ID объекта)
  • Бизнес-события: оплата, регистрация, изменение прав
  • Долгие операции: миграция, импорт, фоновая задача

❌ НЕ логируй:

  • Пароли, токены, JWT, API-ключи
  • Номера карт, CVV, PII (паспорт, ИНН)
  • Целые тела запросов и ответов на больших объёмах
  • Каждый шаг алгоритма в горячем цикле - раздуёт стоимость хранения

Связь логов с трейсами: trace_id в каждой записи

Когда инцидент случился в проде, у вас есть три сигнала: логи, метрики, трейсы. Полезны они вместе. Если в логе видна ошибка, но непонятно, что происходило вокруг - нужно перейти в Jaeger. Это делается через trace_id и span_id, прокинутые в каждую запись лога.

import (
    "go.opentelemetry.io/contrib/bridges/otelslog"
)

// Готовый bridge в OpenTelemetry Logs API. Записи уходят НЕ в stdout,
// а в глобальный LoggerProvider (оттуда по OTLP в Collector) вместе с
// trace_id/span_id активного span из ctx.
// Без настроенного провайдера (sdk/log + OTLP-экспортёр,
// global.SetLoggerProvider из go.opentelemetry.io/otel/log/global)
// записи молча отбрасываются - провайдер по умолчанию no-op.
// Если логи пишутся в stdout для Alloy/Promtail, используйте обёртку
// над JSONHandler из следующего раздела.
logger := otelslog.NewLogger("user-api")
logger.InfoContext(ctx, "user logged in", "user_id", userID)
<?php
declare(strict_types=1);

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Formatter\JsonFormatter;
use OpenTelemetry\Contrib\Logs\Monolog\Handler as OtelMonologHandler;
use OpenTelemetry\API\Trace\TracerProviderInterface;
use OpenTelemetry\API\Trace\Span;

$logger = new Logger('user-api');
$handler = new StreamHandler('php://stdout');
$handler->setFormatter(new JsonFormatter());
$logger->pushHandler($handler);

// Processor: добавляет trace_id и span_id из активного span
$logger->pushProcessor(static function (Monolog\LogRecord $record): Monolog\LogRecord {
    $spanContext = Span::getCurrent()->getContext();
    if ($spanContext->isValid()) {
        $record->extra['trace_id'] = $spanContext->getTraceId();
        $record->extra['span_id'] = $spanContext->getSpanId();
    }
    return $record;
});

$logger->info('user logged in', ['user_id' => $userId]);

В PHP аналог - пакет open-telemetry/opentelemetry-logger-monolog: processor вытаскивает активный span из глобального контекста OTel SDK и пишет trace_id/span_id в каждую запись Monolog.

В Symfony это покрыто бандлами open-telemetry/opentelemetry-auto-symfony плюс open-telemetry/opentelemetry-logger-monolog - подключаются один раз, дальше работают прозрачно для всего приложения.

import logging

from opentelemetry.instrumentation.logging import LoggingInstrumentor

# Готовый bridge (пакет opentelemetry-instrumentation-logging): каждый LogRecord
# получает поля otelTraceID / otelSpanID / otelServiceName из активного span
LoggingInstrumentor().instrument(set_logging_format=False)

logger = logging.getLogger("user-api")
logger.info("user logged in", extra={"user_id": user_id})
# JsonFormatter из раздела выше выведет их как обычные поля (переименовать
# в trace_id/span_id - одна строка в format()):
# {"level":"INFO","msg":"user logged in","user_id":"123",
#  "trace_id":"4bf92f3577b34da6a3ce929d0e0e4736",
#  "span_id":"00f067aa0ba902b7"}

Второй путь - opentelemetry.sdk._logs.LoggingHandler: обычный handler для stdlib logging, который отправляет записи через OTLP в Collector уже с trace context внутри, минуя stdout и Promtail.

Если не хочется тянуть OTel-зависимость, можно достать span context руками - паттерн полезно понимать:

func tracingHandler(inner slog.Handler) slog.Handler {
    return &traceContextHandler{Handler: inner}
}

// Встраиваем slog.Handler: Enabled достаётся «бесплатно» от внутреннего handler-а.
// Интерфейс требует ещё WithAttrs и WithGroup - их переопределяем, иначе
// logger.With(...) вернёт голый внутренний handler и trace_id пропадёт.
type traceContextHandler struct{ slog.Handler }

func (h *traceContextHandler) Handle(ctx context.Context, r slog.Record) error {
    if span := trace.SpanFromContext(ctx); span.SpanContext().IsValid() {
        sc := span.SpanContext()
        r.AddAttrs(
            slog.String("trace_id", sc.TraceID().String()),
            slog.String("span_id", sc.SpanID().String()),
        )
    }
    return h.Handler.Handle(ctx, r)
}

func (h *traceContextHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    return &traceContextHandler{Handler: h.Handler.WithAttrs(attrs)}
}

func (h *traceContextHandler) WithGroup(name string) slog.Handler {
    return &traceContextHandler{Handler: h.Handler.WithGroup(name)}
}
<?php
declare(strict_types=1);

use Monolog\LogRecord;
use OpenTelemetry\API\Trace\Span;

final readonly class TraceContextProcessor
{
    public function __invoke(LogRecord $record): LogRecord
    {
        $context = Span::getCurrent()->getContext();
        if ($context->isValid()) {
            $record->extra['trace_id'] = $context->getTraceId();
            $record->extra['span_id'] = $context->getSpanId();
        }
        return $record;
    }
}

В PHP роль кастомного handler играет Monolog processor. Контекст ctx отсутствует - активный span хранится в Context::getCurrent() SDK-а OpenTelemetry.

import logging

from opentelemetry import trace


class TraceContextFilter(logging.Filter):
    # Роль обёртки над slog.Handler играет Filter на handler-е: он видит каждую
    # запись до форматирования. Явного ctx нет - активный span берётся из contextvars
    def filter(self, record: logging.LogRecord) -> bool:
        span_ctx = trace.get_current_span().get_span_context()
        if span_ctx.is_valid:
            record.trace_id = format(span_ctx.trace_id, "032x")
            record.span_id = format(span_ctx.span_id, "016x")
        return True


def tracing_handler(inner: logging.Handler) -> logging.Handler:
    inner.addFilter(TraceContextFilter())
    return inner

В Grafana и аналогичных UI это даёт «click on log line → open trace» - мгновенный переход между сигналами при расследовании. Без trace_id в логах вы будете руками искать соответствующий trace по таймстампу - это медленно и часто неточно.

Динамический уровень логирования

В проде нельзя постоянно держать DEBUG (объём вырастет в десятки раз и убьёт стоимость). Но и без DEBUG расследовать сложные инциденты тяжело. Решение - менять уровень на лету, без рестарта сервиса.

var levelVar = new(slog.LevelVar) // ноль = LevelInfo

func main() {
    levelVar.Set(slog.LevelInfo)
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: levelVar,
    })
    slog.SetDefault(slog.New(handler))

    http.HandleFunc("/admin/log-level", func(w http.ResponseWriter, r *http.Request) {
        switch r.URL.Query().Get("level") {
        case "debug":
            levelVar.Set(slog.LevelDebug)
        case "info":
            levelVar.Set(slog.LevelInfo)
        case "warn":
            levelVar.Set(slog.LevelWarn)
        case "error":
            levelVar.Set(slog.LevelError)
        }
        slog.InfoContext(r.Context(), "log level changed", "level", levelVar.Level().String())
    })
}
<?php
declare(strict_types=1);

use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\KernelEvents;

// Не handler, а источник уровня: читает текущее значение из Redis
final readonly class LogLevelProvider
{
    public function __construct(private Redis $redis) {}

    public function currentLevel(): Level
    {
        $value = $this->redis->get('app:log_level') ?: 'info';
        return match ($value) {
            'debug' => Level::Debug,
            'warning' => Level::Warning,
            'error' => Level::Error,
            default => Level::Info,
        };
    }
}

// В начале каждого запроса выставляем уровень основному handler-у
final readonly class ApplyLogLevelListener
{
    public function __construct(
        private LogLevelProvider $levels,
        private StreamHandler $handler, // тот handler, что пишет логи приложения
    ) {}

    #[AsEventListener(event: KernelEvents::REQUEST, priority: 1024)]
    public function __invoke(): void
    {
        $this->handler->setLevel($this->levels->currentLevel());
    }
}

// В контроллере /admin/log-level (за внутренней аутентификацией!)
final class LogLevelController
{
    public function __construct(private readonly Redis $redis) {}

    public function set(string $level): void
    {
        $allowed = ['debug', 'info', 'warning', 'error'];
        if (in_array($level, $allowed, true)) {
            $this->redis->set('app:log_level', $level);
        }
    }
}

В PHP-FPM долго живёт мастер-процесс, воркеры рождаются и умирают часто. Один процесс не может атомарно «переключить уровень» сразу всем. Решение - хранить текущий уровень в Redis/APCu и в начале каждого запроса вызывать setLevel() у основного handler-а (listener выше). FilterHandler для этого не подходит: он принимает фиксированные границы уровней при создании и сам ничего не перечитывает.

import logging
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs, urlparse

root = logging.getLogger()
root.setLevel(logging.INFO)  # аналог slog.LevelVar: setLevel меняет уровень на лету, без рестарта


class LogLevelHandler(BaseHTTPRequestHandler):
    # В FastAPI это @app.post("/admin/log-level"), в Django - view; логика та же
    def do_GET(self) -> None:
        url = urlparse(self.path)
        if url.path != "/admin/log-level":
            self.send_error(404)
            return
        match parse_qs(url.query).get("level", [""])[0]:
            case "debug":
                root.setLevel(logging.DEBUG)
            case "info":
                root.setLevel(logging.INFO)
            case "warn":
                root.setLevel(logging.WARNING)
            case "error":
                root.setLevel(logging.ERROR)
        logging.info("log level changed", extra={"level": logging.getLevelName(root.level)})
        self.send_response(204)
        self.end_headers()


if __name__ == "__main__":
    HTTPServer(("", 8080), LogLevelHandler).serve_forever()

setLevel потокобезопасен и действует сразу на все логгеры процесса. Но под gunicorn/uvicorn с несколькими воркерами каждый процесс держит свой уровень - как и в PHP-FPM, переключать нужно либо каждый воркер, либо через общее хранилище (Redis), которое Filter перечитывает.

slog.LevelVar в Go атомарно перечитывается на каждый вызов лога - это безопасно при конкурентной нагрузке. Use case: SRE заметил аномалию, включает DEBUG на 10 минут на одном инстансе, собирает детали, возвращает INFO. Endpoint должен быть закрыт от внешнего мира (только во внутренней сети, под аутентификацией) - иначе атакующий уронит вас через flood DEBUG-логов.

Redaction чувствительных полей через ReplaceAttr

Раньше уже было сказано: не пишите пароли и токены в логи. На практике их туда заносят случайно - структура, в которой лежит password, передаётся в slog.Any("user", user). Защита - фильтр на уровне Handler-а: список запрещённых ключей.

var redactedKeys = map[string]bool{
    "password":     true,
    "token":        true,
    "card_number":  true,
    "ssn":          true,
    "authorization": true,
}

func redactHandler(w io.Writer) slog.Handler {
    return slog.NewJSONHandler(w, &slog.HandlerOptions{
        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
            if redactedKeys[strings.ToLower(a.Key)] {
                return slog.String(a.Key, "[REDACTED]")
            }
            return a
        },
    })
}

// Использование
slog.Info("login attempt",
    "email", "user@example.com",
    "password", "secret123", // → "[REDACTED]"
)
<?php
declare(strict_types=1);

use Monolog\LogRecord;

final readonly class RedactingProcessor
{
    private const REDACTED_KEYS = [
        'password',
        'token',
        'card_number',
        'ssn',
        'authorization',
    ];

    public function __invoke(LogRecord $record): LogRecord
    {
        foreach ($record->context as $key => $_) {
            if (in_array(strtolower((string) $key), self::REDACTED_KEYS, true)) {
                $record->context[$key] = '[REDACTED]';
            }
        }
        return $record;
    }
}

$logger->pushProcessor(new RedactingProcessor());
$logger->info('login attempt', [
    'email' => 'user@example.com',
    'password' => 'secret123', // → '[REDACTED]'
]);

В PHP redaction делается processor-ом, который пробегает по $record->context и заменяет значения по ключам.

import logging
import sys
from typing import TextIO

REDACTED_KEYS = {"password", "token", "card_number", "ssn", "authorization"}


class RedactingFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        """Аналог ReplaceAttr: видит каждую запись до форматирования.

        Подменяет значения полей, пришедших через extra.
        """
        for key in vars(record):
            if key.lower() in REDACTED_KEYS:
                setattr(record, key, "[REDACTED]")
        return True


def redact_handler(stream: TextIO = sys.stdout) -> logging.Handler:
    handler = logging.StreamHandler(stream)
    handler.setFormatter(JsonFormatter())
    handler.addFilter(RedactingFilter())
    return handler


# Использование. force=True снимает handler из блока выше: без него
# второй basicConfig молча ничего не делает, и фильтр не подключится
logging.basicConfig(level=logging.INFO, handlers=[redact_handler()], force=True)
logging.info("login attempt", extra={
    "email": "user@example.com",
    "password": "secret123",  # -> "[REDACTED]"
})

Processor вызывается для каждой записи перед сериализацией. Можно маскировать по pattern (regex на «похоже на номер карты»), но это дороже и даёт false positives. Защита от случайного попадания PII лучше работает на этапе review: чёткие правила, какие поля можно логировать.

Logger через context, а не глобальный slog.Default

Глобальный slog.Default() неудобен: нельзя подменить в тесте, нельзя обогатить request-scope атрибутами (correlation_id, user_id). Прокидывание logger через context решает обе проблемы.

type ctxKey struct{}

var loggerKey = ctxKey{}

func WithLogger(ctx context.Context, l *slog.Logger) context.Context {
    return context.WithValue(ctx, loggerKey, l)
}

func LoggerFromCtx(ctx context.Context) *slog.Logger {
    if l, ok := ctx.Value(loggerKey).(*slog.Logger); ok {
        return l
    }
    return slog.Default()
}

// middleware: обогатить logger correlation_id, прокинуть в ctx
func loggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        corrID := r.Header.Get("X-Correlation-ID")
        if corrID == "" {
            corrID = uuid.New().String()
        }
        l := slog.Default().With(
            "correlation_id", corrID,
            "method", r.Method,
            "path", r.URL.Path,
        )
        ctx := WithLogger(r.Context(), l)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// в handler
func usersHandler(w http.ResponseWriter, r *http.Request) {
    l := LoggerFromCtx(r.Context())
    l.Info("fetching users", "limit", 100)
    // Логи автоматически содержат correlation_id, method, path
}
<?php
declare(strict_types=1);

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Uid\Uuid;
use Monolog\LogRecord;

final class RequestContextSubscriber implements EventSubscriberInterface
{
    public function __construct(private RequestContextHolder $holder) {}

    public static function getSubscribedEvents(): array
    {
        return [KernelEvents::REQUEST => ['onRequest', 256]];
    }

    public function onRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $this->holder->set(
            $request->headers->get('X-Correlation-ID') ?? Uuid::v4()->toRfc4122(),
            $request->getMethod(),
            $request->getPathInfo(),
        );
    }
}

// Processor, добавляющий контекст к каждой записи
final readonly class RequestContextProcessor
{
    public function __construct(private RequestContextHolder $holder) {}

    public function __invoke(LogRecord $record): LogRecord
    {
        $record->extra['correlation_id'] = $this->holder->correlationId();
        $record->extra['method'] = $this->holder->method();
        $record->extra['path'] = $this->holder->path();
        return $record;
    }
}

// В контроллере: LoggerInterface уже содержит все атрибуты
final class UsersController
{
    public function __construct(private readonly LoggerInterface $logger) {}

    public function list(): void
    {
        $this->logger->info('fetching users', ['limit' => 100]);
    }
}

В PHP нет context.Context - его роль играет request-scope DI-контейнер. Сервис получает обогащённый logger через конструктор, а добавление contextual-полей делает EventSubscriber на kernel.request.

import logging
import uuid
from contextvars import ContextVar, Token
from typing import Any, Callable, Iterable

WSGIApp = Callable[[dict[str, Any], Callable[..., Any]], Iterable[bytes]]

# Роль context.Context играет ContextVar: значение видно всему коду
# в рамках текущего запроса (поток или asyncio-задача), но не соседним запросам
_logger_var: ContextVar[logging.LoggerAdapter | None] = ContextVar("logger", default=None)


def with_logger(logger: logging.LoggerAdapter) -> Token:
    return _logger_var.set(logger)


def logger_from_ctx() -> logging.LoggerAdapter:
    if (logger := _logger_var.get()) is not None:
        return logger
    return ContextAdapter(logging.getLogger("app"), {})


# middleware: обогатить logger correlation_id, прокинуть в ctx
def logging_middleware(app: WSGIApp) -> WSGIApp:
    def wrapper(environ: dict[str, Any], start_response: Callable[..., Any]) -> Iterable[bytes]:
        corr_id = environ.get("HTTP_X_CORRELATION_ID") or str(uuid.uuid4())
        logger = ContextAdapter(logging.getLogger("app"), {
            "correlation_id": corr_id,
            "method": environ["REQUEST_METHOD"],
            "path": environ["PATH_INFO"],
        })
        token = with_logger(logger)
        try:
            return app(environ, start_response)
        finally:
            _logger_var.reset(token)

    return wrapper


# в handler
def users_handler(environ: dict[str, Any], start_response: Callable[..., Any]) -> Iterable[bytes]:
    logger = logger_from_ctx()
    logger.info("fetching users", extra={"limit": 100})
    # Логи автоматически содержат correlation_id, method, path
    start_response("200 OK", [("Content-Type", "application/json")])
    return [b"[]"]

В тесте подмена тривиальна: with_logger(ContextAdapter(logging.getLogger("test"), {})) перед вызовом handler-а - без monkeypatch глобального состояния.

В DI-фреймворках (Wire, Fx, Symfony DI) base-logger создаётся один раз при старте, дальше каждый сервис получает свою копию с прилипшими атрибутами. В Symfony это делается через monolog.logger теги каналов: UserRepository получает @logger.user_repo, и каждая запись отмечена 'channel' => 'user_repo'.

Производительность

slog аллоцирует, если передавать slog.Any(key, val). Для горячих путей используй типизированные хелперы:

slog.LogAttrs(ctx, slog.LevelInfo, "request",
    slog.String("path", path),
    slog.Int("status", status),
    slog.Duration("dur", elapsed),
)
<?php
declare(strict_types=1);

// ХОРОШО: placeholders + плоский context
$this->logger->info('request {method} {path}', [
    'method' => $method,
    'path' => $path,
    'status' => $status,
    'duration_ms' => $durationMs,
]);

// ПЛОХО: тяжёлый объект - сериализатор пройдёт по всем полям
$this->logger->info('request', ['request' => $request]);

В PHP горячий путь обычно упирается не в логгер, а в сериализацию. Главная оптимизация - не передавать тяжёлые объекты в context. Используй PSR-3 placeholder-синтаксис для интерполяции. Подставляет значения PsrLogMessageProcessor (в Symfony MonologBundle он подключён по умолчанию, в чистом Monolog его добавляют через pushProcessor()), и делает это только для записей, прошедших фильтр уровня. Без него в логе останется буквально request {method} {path}.

В Monolog можно отфильтровать тяжёлые контексты на уровне Handler через FilterHandler или вынести их в отдельный канал (debug-канал, который пишет только в файл и не уходит в Loki).

import logging

logger = logging.getLogger("app")

# ХОРОШО: %-плейсхолдеры - строка собирается только если уровень включён,
# а значения уходят отдельными полями через extra
logger.info("request %s %s", method, path, extra={
    "status": status,
    "duration_ms": elapsed_ms,
})

# ПЛОХО: f-string форматируется всегда, даже если INFO выключен
logger.info(f"request {method} {path} {status} {elapsed_ms}")

# Дорогие вычисления для DEBUG - только под проверкой уровня
if logger.isEnabledFor(logging.DEBUG):
    logger.debug("payload", extra={"body": expensive_dump(payload)})

Типизированных хелперов вроде slog.Int нет: горячий путь упирается в форматирование и синхронный I/O handler-а. Второй приём - QueueHandler + QueueListener: запись кладётся в очередь, а сериализацию и запись на диск делает фоновый поток.

Sampling логов на горячих путях

Если endpoint обрабатывает 10K RPS и каждый пишет 5 строк лога - это 50K строк/сек. Сэмплирование (например, логировать каждый 100-й запрос или все ошибочные плюс 1% успешных) сокращает объём при сохранении репрезентативности. Реализуется как кастомный slog.Handler, который пропускает часть записей.

// Как и traceContextHandler выше: встраиваем slog.Handler ради Enabled,
// а WithAttrs/WithGroup переопределяем, чтобы сэмплирование не терялось в logger.With(...)
type samplingHandler struct {
    slog.Handler
    rate int
}

func (h *samplingHandler) Handle(ctx context.Context, r slog.Record) error {
    if r.Level >= slog.LevelError || rand.Intn(h.rate) == 0 {
        return h.Handler.Handle(ctx, r)
    }
    return nil
}

func (h *samplingHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    return &samplingHandler{Handler: h.Handler.WithAttrs(attrs), rate: h.rate}
}

func (h *samplingHandler) WithGroup(name string) slog.Handler {
    return &samplingHandler{Handler: h.Handler.WithGroup(name), rate: h.rate}
}
<?php
declare(strict_types=1);

use Monolog\Handler\AbstractHandler;
use Monolog\Handler\HandlerInterface;
use Monolog\LogRecord;
use Monolog\Level;

final class SamplingHandler extends AbstractHandler
{
    public function __construct(
        private readonly HandlerInterface $inner,
        private readonly int $rate,
    ) {
        parent::__construct();
    }

    public function handle(LogRecord $record): bool
    {
        if ($record->level->value >= Level::Error->value || random_int(1, $this->rate) === 1) {
            return $this->inner->handle($record);
        }
        return false;
    }
}

В Monolog сэмплирование реализуется через SamplingHandler (часть пакета) или собственный handler-обёртку.

import logging
import random


class SamplingFilter(logging.Filter):
    # Роль handler-обёртки играет Filter на handler-е: False - запись отброшена
    def __init__(self, rate: int) -> None:
        super().__init__()
        self._rate = rate

    def filter(self, record: logging.LogRecord) -> bool:
        return record.levelno >= logging.ERROR or random.randrange(self._rate) == 0


handler.addFilter(SamplingFilter(rate=100))

Мини-практика

Добавь middleware для логирования HTTP-запросов: метод, путь, статус, длительность, correlation ID. Используй slog.LogAttrs и пробрось correlation ID в context. Прогони сервер через curl -H "X-Correlation-ID: test-123" и убедись, что ID появляется в логах handler-а.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.