promtail-config.yaml
Тема дорожной карты · Loki
Файл promtail-config.yaml управляет всеми аспектами поведения Promtail: от адреса прослушивания для проверок работоспособности до того, какие файлы логов он отслеживает и как преобразует строки логов перед отправкой в Grafana Loki. Разделы верхнего уровня: server (HTTP-адрес прослушивания для /ready и /metrics), positions (путь к файлу позиций, отслеживающему смещения в файлах), clients (список конечных точек Loki с опциональной аутентификацией) и scrape_configs (список заданий, определяющих цели логов и этапы конвейера). В разделе clients поле url указывает на push API Loki, например http://loki:3100/loki/api/v1/push, а также можно задать tenant_id для многопользовательских развёртываний Loki. Раздел positions важен для надёжности — по умолчанию он указывает на /tmp/positions.yaml, но в продакшене его следует изменить на постоянный путь, чтобы Promtail мог корректно возобновить работу после перезапуска. Хорошо структурированный promtail-config.yaml минимизирует кардинальность меток, назначая лишь небольшой набор стабильных меток в static_configs и извлекая дополнительные метаданные через этапы конвейера.
Как это работает
promtail-config.yaml: канонический log shipper для Loki. Tail-ит файлы + container stdout, добавляет labels (из service discovery — K8s pods, file paths, syslog), парсит log lines через pipeline stages (regex, json, labels, output, timestamp, template), шипит в Loki HTTP API. В Kubernetes работает как DaemonSet — логи каждой ноды идут в Loki. Promtail сменяется Grafana Alloy (merged OTel-style агент) — новые деплои могут предпочесть Alloy.
Когда применять
В K8s деплойте Promtail (или Alloy) как DaemonSet + kubernetes_sd для discovery. Labels в scrape_configs — low-cardinality. Pipeline stages json/regex для extract structured полей ДО shipping — экономит query-time работу. Pin версию агента + тестируйте pipeline changes на sample логах.
Типичные ошибки
Ловушки promtail-config.yaml: extract high-cardinality labels в pipeline (убивает Loki); не capture pod restarts через positions file (логи теряются на рестарте); деплой Promtail без resource limits (OOM на log spikes); regex stage когда json работает (медленнее).