Структурированное логирование с slog
Структурированное логирование с slog
С Go 1.21 в stdlib появился log/slog - структурированное логирование из коробки. Раньше команды выбирали между logrus, zap, zerolog; теперь у всех есть единый стандартный API.
Почему не 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 связывает их вместе.
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))
- Python - logging: уровни, handlers, formatters, root pitfalls - тот же подход в Python: RotatingFileHandler, JSON-вывод, root logger anti-patterns
Мини-практика
Добавь middleware для логирования HTTP-запросов: метод, путь, статус, длительность, correlation ID. Используй slog.LogAttrs и пробрось correlation ID в context. Прогони сервер через curl -H "X-Correlation-ID: test-123" и убедись, что ID появляется в логах handler-а.