Filebeat подробно: входы и модули

Глубокое погружение в Filebeat: как настроить входы, склеить многострочные стектрейсы и использовать готовые модули.

Вход (input) Filebeat — это описание источника логов: какие файлы читать, как их парсить на строки и какие поля добавить.

Базовая конфигурация

Filebeat настраивается одним YAML-файлом filebeat.yml. Минимальная конфигурация: один вход типа filestream (современный вход для файлов) и выход. Вот сбор логов nginx с отправкой в Elasticsearch напрямую:

filebeat.inputs:
  - type: filestream
    id: nginx-access
    paths:
      - /var/log/nginx/access.log
    fields:
      log_type: nginx-access
    fields_under_root: true

output.elasticsearch:
  hosts: ["http://es01:9200"]
  index: "logs-nginx-%{+yyyy.MM.dd}"

Поле fields добавляет к каждому событию метку log_type, чтобы потом отличать источники. fields_under_root: true кладёт это поле в корень документа, а не во вложенный объект fields.

Harvester: как читается файл

Под капотом каждый совпавший файл обслуживает harvester — поток, который открывает файл, читает строки и держит позицию. Filebeat периодически сканирует paths на новые файлы (например, после ротации access.log.1 → новый access.log) и запускает для них harvester. Прочитанное смещение хранится в registry, поэтому перезапуск Filebeat не приводит к повторной отправке всего файла.

  paths: /var/log/nginx/access.log
            |
   filestream сканирует, находит файл
            |
   harvester читает строки, помнит offset
            |
   registry: { access.log: offset 84512 }  -- переживёт рестарт

Мультилайн: склеиваем стектрейсы

Java-стектрейс или Python-traceback занимает много строк, но это одно событие. По умолчанию Filebeat шлёт каждую строку отдельно — стектрейс развалится на десяток несвязных записей. Лечится настройкой parsers с multiline: строки, не начинающиеся с даты, приклеиваются к предыдущей.

filebeat.inputs:
  - type: filestream
    id: app-log
    paths:
      - /var/log/app/*.log
    parsers:
      - multiline:
          type: pattern
          pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
          negate: true
          match: after

Читается так: «если строка не (negate: true) начинается с даты, приклей её after (к предыдущей)». В итоге весь многострочный стектрейс становится одним событием.

Модули: готовые рецепты

Писать парсинг для популярных сервисов вручную не нужно — у Filebeat есть модули: готовые наборы конфигурации входа, парсинга и даже дашбордов Kibana для nginx, apache, mysql, system, kafka и десятков других. Включается модуль одной командой:

filebeat modules enable nginx
filebeat setup --dashboards   # загрузит дашборды в Kibana

После этого Filebeat сам знает, где лежат логи nginx и как разобрать их на поля url.path, http.response.status_code, source.ip по схеме ECS (Elastic Common Schema — единый стандарт имён полей). Модули — самый быстрый способ начать собирать логи типового сервиса грамотно.

Как работает под капотом: ingest-пайплайн вместо Logstash

Когда Filebeat пишет в Elasticsearch напрямую, разбор строки на поля делает не Logstash, а ingest-пайплайн внутри самого Elasticsearch — набор процессоров (включая grok), который ES применяет к документу перед индексацией. Модули Filebeat как раз устанавливают такой ingest-пайплайн. Это и есть тот случай, когда Logstash не нужен: лёгкий Filebeat + ingest-пайплайн ES закрывают весь конвейер.

Доставка и идемпотентность

Filebeat гарантирует доставку «хотя бы один раз» (at-least-once): он не удалит запись из своей очереди, пока выход не подтвердит приём. Обратная сторона этой гарантии — возможность дублей. Если Filebeat отправил пачку событий, но упал до того, как получил подтверждение, после перезапуска он отправит её снова — и в Elasticsearch окажутся две копии. На практике с этим борются, задавая событиям детерминированный идентификатор документа (например, на основе содержимого и позиции в файле): тогда повторная отправка просто перезапишет тот же документ, а не создаст дубль. Понимать это важно: «потеря логов» и «дубли логов» — две стороны одной медали надёжной доставки, и выбор между at-least-once и сложной точной семантикой определяет, с какой из проблем вы будете иметь дело.

Полезно также знать про автообнаружение в контейнерных средах: Filebeat умеет сам подхватывать логи новых контейнеров по их label'ам (autodiscover), не требуя ручной правки конфигурации на каждый сервис. Это та же идея, что и модули, но для динамических сред, где сервисы появляются и исчезают: правило «у всех контейнеров с меткой logging=enabled читать stdout» избавляет от ручного перечисления путей и хорошо стыкуется с миром Kubernetes.

Частые ошибки

• Забыть про мультилайн. Самая частая боль: стектрейсы разваливаются на строки, и в Kibana вместо одной ошибки — каша из обрывков. Всегда настраивайте multiline для логов с многострочными трейсами.
• Путать filestream и старый log input. Тип log устарел; для новых конфигов используйте filestream.
• Дубли после смены id входа. Поле id входа привязано к registry. Поменяли id — Filebeat считает вход новым и может перечитать файлы заново.

Итоги

• Filebeat настраивается через входы (filestream) в filebeat.yml; harvester читает файлы и помнит позицию в registry.
• Многострочные стектрейсы склеиваются в одно событие настройкой multiline — это обязательно.
• Модули дают готовый сбор и парсинг для популярных сервисов и грузят дашборды Kibana.
• При прямой записи в ES разбор делает ingest-пайплайн Elasticsearch — Logstash тогда не нужен.