Обработка логов на агенте

На этой странице:

• Где задаются правила
• Порядок применения
• Типы правил
  • exclude_at_match — исключить записи
  • include_at_match — оставить только нужные записи
  • mask_sequences — маскировать данные
  • multi_line — склеить многострочные записи
  • exclude_truncated — исключить обрезанные записи
• Автоматическая склейка многострочных записей
• Размер сообщения
• Проверка правил

Агент обрабатывает каждую запись лога до отправки на ProtoOBP Backend. Отброшенные записи не передаются по сети и не занимают место в хранилище, а замаскированные данные не покидают хост. Обработка выполняется для логов, которые собирает агент. Логи, отправленные напрямую в proto-log-storage или через OpenTelemetry Collector (см. Получение логов), агентом не обрабатываются.

Где задаются правила

Каждое правило — объект с полями type (тип), name (имя, обязательно) и, для большинства типов, pattern (регулярное выражение в синтаксисе RE2: без просмотра вперёд и назад).

Пример для файла интеграции:

# conf.d/myapp.d/conf.yaml
logs:
  - type: file
    path: /var/log/myapp/*.log
    service: myapp
    source: java
    log_processing_rules:
      - type: exclude_at_match
        name: drop_healthchecks
        pattern: 'GET /(health|ready)'

То же в переменной окружения (для Docker и Kubernetes):

POBP_LOGS_CONFIG_PROCESSING_RULES='[{"type":"exclude_at_match","name":"drop_healthchecks","pattern":"GET /(health|ready)"}]'

В строке YAML в одинарных кавычках обратная косая черта пишется один раз ('\d+'), в двойных кавычках и в JSON — дважды ("\\d+").

Порядок применения

1. Сначала выполняется склейка многострочных записей (multi_line или автоматическая): дальше правила видят уже склеенную запись.
2. Затем по порядку применяются глобальные правила, после них — правила источника.
3. Каждое правило получает запись в том виде, в каком её оставили предыдущие. Например, если mask_sequences стоит перед exclude_at_match, исключающее правило проверяет уже замаскированный текст.
4. Как только запись отброшена (exclude_at_match, include_at_match, exclude_truncated), следующие правила к ней не применяются.

Типы правил

exclude_at_match — исключить записи

Запись, в которой найдено совпадение с pattern, отбрасывается.

log_processing_rules:
  - type: exclude_at_match
    name: drop_debug
    pattern: '\b(DEBUG|TRACE)\b'

include_at_match — оставить только нужные записи

Отправляются только записи с совпадением; остальные отбрасываются. Если задано несколько правил include_at_match, запись должна совпасть с каждым. Чтобы оставить записи, совпадающие хотя бы с одним из вариантов, объедините их в одном выражении через |:

log_processing_rules:
  - type: include_at_match
    name: only_errors
    pattern: '\b(ERROR|FATAL|CRITICAL)\b'

mask_sequences — маскировать данные

Каждое совпадение заменяется строкой replace_placeholder. На группы захвата можно ссылаться как ${1}, ${2}:

log_processing_rules:
  - type: mask_sequences
    name: mask_password
    pattern: '(password=)\S+'
    replace_placeholder: '${1}[MASKED]'

Готовые правила для номеров банковских карт и других чувствительных данных — в разделе Маскирование данных в логах.

multi_line — склеить многострочные записи

Стеки исключений, тексты SQL-запросов и другие многострочные сообщения по умолчанию разбиваются на отдельные записи по строкам. Правило multi_line задаёт шаблон начала записи: строка, совпадающая с pattern с первого символа, открывает новую запись, а все следующие строки до следующего совпадения добавляются к ней.

log_processing_rules:
  - type: multi_line
    name: new_log_start_with_date
    pattern: '\d{4}-\d{2}-\d{2}'      # запись начинается с даты 2026-10-15

Шаблон автоматически привязывается к началу строки, ^ указывать не нужно. Правило multi_line задаётся только для источника или контейнера, не глобально. Если у источника есть multi_line, автоматическая склейка для него не применяется.

Примеры для конкретных систем — на страницах PostgreSQL и MySQL.

exclude_truncated — исключить обрезанные записи

Отбрасывает записи, которые агент обрезал из-за превышения максимального размера. Поле pattern не нужно:

log_processing_rules:
  - type: exclude_truncated
    name: drop_truncated

Автоматическая склейка многострочных записей

Если формат начала записи заранее неизвестен или источников много, включите автоматическое определение. Агент распознаёт начало записи по метке времени в начале строки и по типовым шаблонам и склеивает продолжения с предыдущей записью. JSON-объекты, разбитые на несколько строк, также собираются в одну запись.

Для всех источников:

logs_config:
  auto_multi_line_detection: true

Для одного источника:

logs:
  - type: file
    path: /var/log/myapp/*.log
    service: myapp
    source: java
    auto_multi_line_detection: true

Если агент ошибается в определении начала записи, подскажите ему образцы:

logs_config:
  auto_multi_line_detection: true
  auto_multi_line_detection_custom_samples:
    - sample: "[INFO] 2026-10-15 10:12:03 Request started"   # образец строки, начинающей запись
    - regex: '^\[\w+\] \d{4}-\d{2}-\d{2}'                  # или регулярное выражение
      label: start_group

Склеенные записи получают тег multiline:<источник>, обрезанные — тег truncated:<причина>. Отключить эти теги можно параметрами logs_config.tag_multi_line_logs: false и logs_config.tag_truncated_logs: false.

Размер сообщения

Запись длиннее logs_config.max_message_size_bytes (по умолчанию 900000 байт) агент обрезает и отправляет частями; к обрезанным частям добавляется метка ...TRUNCATED... и тег truncated:<причина>. Склеенная многострочная запись подчиняется тому же ограничению.

logs_config:
  max_message_size_bytes: 256000

Чтобы не хранить обрезанные части, используйте правило exclude_truncated.

Проверка правил

1. Перезапустите агента (правила в лейблах и аннотациях применяются при перезапуске контейнера).
2. Выполните protoobp-agent status (см. Команды и проверка работы). В разделе Logs Agent для каждого источника видны ошибки конфигурации, в том числе некорректные правила: отсутствие name или pattern, неверное регулярное выражение, неизвестный type.
3. Командой protoobp-agent stream-logs посмотрите поток записей после обработки — в нём видно, что маскирование сработало, а исключённые записи не попадают в поток.
4. Проверьте результат в Logs Explorer.