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

Mon, 01 Jan 0001 00:00:00 +0000

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

Где задаются правила
Порядок применения
Типы правил
Автоматическая склейка многострочных записей
Размер сообщения
Проверка правил

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

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

Уровень	Где	Действует на
Глобальный	`logs_config.processing_rules` в `protoobp.yaml` или переменная `POBP_LOGS_CONFIG_PROCESSING_RULES` (JSON)	все логи, которые собирает агент
Источник	`log_processing_rules` в секции `logs:` файла интеграции `conf.d/<интеграция>.d/conf.yaml`	один источник логов
Контейнер	`log_processing_rules` в лейбле `com.protoobp.ad.logs` или аннотации `ad.protoobp.com/<контейнер>.logs`	логи одного контейнера — см. Автообнаружение

Каждое правило — объект с полями 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+").

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

Сначала выполняется склейка многострочных записей (multi_line или автоматическая): дальше правила видят уже склеенную запись.
Затем по порядку применяются глобальные правила, после них — правила источника.
Каждое правило получает запись в том виде, в каком её оставили предыдущие. Например, если mask_sequences стоит перед exclude_at_match, исключающее правило проверяет уже замаскированный текст.
Как только запись отброшена (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

Поле образца	Назначение
`sample`	Пример строки; запись считается похожей, если совпадает доля токенов не ниже `match_threshold` (по умолчанию `0.75`)
`regex`	Регулярное выражение вместо `sample` (одно из двух)
`label`	`start_group` — строка начинает запись (по умолчанию), `aggregate` — строка приклеивается к предыдущей, `no_aggregate` — строка всегда отдельная запись

Склеенные записи получают тег 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.

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

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

Документация Proto Observability Platform – processing_rules