[Документация Yandex Cloud](../../../../index.md) > [Monium](../../../index.md) > Поставка данных > [Unified Agent](index.md) > Конфигурирование > Фильтры # Фильтры Фильтр можно описать в секции `routes` внутри элемента `channel`:`pipe`:`filter`. Либо в секции именованных цепочек преобразований `pipes`. Общий формат описания фильтра: ```yaml - filter: plugin: ... # имя плагина id: ... # (рекомендуемый) идентификатор фильтра, используется в метриках и логах config: # конфигурация фильтра ... ``` ## Фильтр assign {#assign_filter} Фильтр для присвоения метаданных сессии или сообщениям. Значение метаданных формируется при помощи шаблона. Синтаксис шаблона: `{key:format|default}`. Экранирование фигурных скобок осуществляется при помощи `\`: `"\{\}"`. Значение `key`: - `_timestamp` — временная метка сообщения; - `_payload` — тело сообщения; - `key` — метаданные с ключом key. Если ключ метаданных не найден на уровне сообщения (в разделе `message`), будет выполнен поиск ключа в метаданных сессии. Если ключ не найден на уровне сессии, будет использовано значение по умолчанию `({_host|default_host})` или пустая строка, если значение по умолчанию не указано. Также в качестве значения `key` можно указывать макросы: - `$host_name` — локальное имя машины; - `$short_host_name` — краткое локальное имя машины (до первой точки); - `$env('name')` — переменная окружения с именем `name`; - `$file('name')` — содержимое файла с именем `name`. Поддерживается подстановка аргумента макроса из метаданных. Например, в случае `$file(name)` имя файла будет взято из метаданных с ключом `name`. Значение `format` — строка форматирования в формате [strftime](http://man7.org/linux/man-pages/man3/strftime.3.html). Может быть указана только для `_timestamp`. Значение `default`: - Определяет значение по умолчанию, если нет метаданных с таким ключом или пустой `_payload`. - Не может быть указан для `_timestamp`, так как `_timestamp` есть всегда. - Поддерживается для макросов `$env` и `$file`. Применяется, если указанный файл не найден или значение переменной окружения — пустая строка. - По умолчанию используется пустая строка. Описание параметров: ```yaml - filter: plugin: assign config: # Должен быть указан хотя бы один из разделов message или session. # Значения, которые нужно записать в метаданные сообщения. # Внутри message должен быть список одноэлементных функций map, у которых ключ — имя метаданных, значение — шаблон форматирования. # Макросы в фигурных скобках в шаблоне могут содержать ключи метаданных ({_host}) и встроенные функции ({$file('test-file')}). # Если ключ метаданных не найден на уровне сообщения (в разделе `message`), будет выполнен поиск ключа в метаданных сессии. # Если ключ не найден на уровне сессии, будет использовано значение по умолчанию `({_host|default_host})` или пустая строка, если значение по умолчанию не указано. # Ниже приведено несколько примеров таких шаблонов. message: # необязательный, по умолчанию не задан # Пример результата: 'Nov 27 21:03:24 test-host test-app:test_payload'. # Метка времени форматируется в соответствии с форматом strftime (http://man7.org/linux/man-pages/man3/strftime.3.html). # В этом примере значение _app 'test-app:', с двоеточием на конце — типичный результат разбора syslog-сообщения. - _payload: "{_timestamp:%b %d %H:%M:%S} {_host} {_app}{_payload}" # Подставить вместо $file значение из файла 'test-file'. # Если содержимое файла test-file равно test-content, то на выходе получится 'prefix_test-content_suffix'. - m1: "prefix_{$file('test-file')}_suffix" # Подставить значение из файла, имя которого можно взять из метаданных с ключом test-file-name. - m2: "prefix_{$file(test-file-name)}_suffix" # Подставить значение из переменной окружения 'test-env'. - m3: "prefix_{$env('test-env')}_suffix" # Подставить значение из переменной окружения, имя которой взять из метаданных с ключом test-env-name. - m4: "prefix_{$env(test-env-name)}_suffix" # Подставить имя хоста, на котором запущен агент. - m5: "$host_name" # Аналогично $host_name, только без домена — префикс до первой точки. # Например, если $host_name равен 'lbk-dev-02.search.yandex.net', то в $short_host_name будет значение 'lbk-dev-02'. - m6: "$short_host_name" # Значения, которые нужно присвоить в метаданные сессии. session: # необязательный, по умолчанию не задан # Аналогично message. - m1: v1 - m2: v2 ``` ## Фильтр convert_metrics {#convert_metrics_filter} Фильтр для преобразования метрик между разными форматами. Формат сообщений на входе берется из метаданных сессии с ключом `_metrics_format` (если он существует), либо из метаданных сообщения с тем же ключом (если он существует). Если формат входящего сообщения определить не удалось (`_metrics_format` не указан ни на уровне сессии, ни на уровне сообщения), то входящее сообщение отбрасывается и счетчик `RejectedMessages` этого плагина увеличивается на один. Описание параметров: ```yaml - filter: plugin: convert_metrics config: # Выходной формат, в который нужно преобразовать входящий набор метрик. # Должен быть указан ровно один из вложенных элементов. format: # обязательный # Преобразовать в JSON-формат Monium Metrics (../../../api-ref/MetricsData/write.md) json: # Нужно ли склеивать метрики с одним и тем же набором меток. # Возможные значения: default (не склеивать), merge_metrics (склеивать). merging_mode: default # необязательный, значение по умолчанию default (не склеивать) # Нужно ли форматировать JSON в человекочитаемый формат (с переносами строк и отступами). # Задает размер отступов, если 0 — форматировать не нужно. indentation: 0 # необязательный, по умолчанию форматирование выключено # Набор меток, которые дополнительно нужно добавить к выходному набору метрик. labels: # необязательный, по умолчанию не указан l1: v1 l2: v2 # Значение времени по умолчанию, которое нужно добавить к выходному набору метрик. # Поддерживаются два варианта синтаксиса значений этих параметров — абсолютный и относительный. # В абсолютном формате ожидается значение времени в формате ISO 8601. # Примеры: 2014-03-25 03:59:56.654563, 2012-11-23 11:12:13, 2012-11-23, 1990-03-15T15:10:12. # В относительном формате требуется указать смещение от одного из предопределенных значений: # * now — текущее время; # * today — начало текущих суток; # * yesterday — начало предыдущих суток; # * tomorrow — начало следующих суток. # Смещение состоит из произвольного числа временных дельт, разделенных операторами + или -. # Возможные значения для дельты: # * m — минута; # * h — час; # * d – сутки; # * w – неделя; # Например, --since yesterday оставит сообщения за вчера и сегодня, а --since now-5m --until now-5m+10s — за интервал в 10 секунд, который начался пять минут назад. # По умолчанию дельты отсчитываются от now, то есть вместо now-2m можно указать -2m. common_time: null # необязательный, по умолчанию не задан ``` ## Фильтр filter_metrics {#filter_metrics_filter} Фильтр позволяет сократить набор передаваемых метрик на основе значений меток. ```yaml - filter: plugin: filter_metrics config: # Условие на метрики, которые нужно оставить. Все остальные будут отфильтрованы. match: "{name=gauge-*}" # обязательный ``` Читайте также [описание синтаксиса запросов](../../querying.md#selectors). ## Фильтр match {#match_filter} Фильтрация сообщений по метаданным — фильтр пропускает только те сообщения, которые содержат все перечисленные метаданные. Описание параметров: ```yaml - filter: plugin: match config: # Метаданные сессии в формате `ключ:значение`. session: # необязательный a: b # Метаданные сообщения в формате `ключ:значение`. message: # необязательный c: d e: f # В приведенной выше конфигурации фильтр будет пропускать только те сообщения, у которых: # * метаданные сессии содержат ключ "a" со значением "b"; # * метаданные сообщения содержат ключ "c" со значением "d" и ключ "e" со значением "f" (обязательно оба). # При этом метаданные могут дополнительно содержать любые другие ключи. ``` ## Фильтр transform_metric_label {#transform_metric_label_filter} Фильтр позволяет переименовать или добавить префикс к метке для метрики. Описание параметров: ```yaml - filter: plugin: transform_metric_label config: # Имя метки, которую нужно преобразовать. label: name # обязательный # Добавить префикс к значению метки. add_value_prefix: ua # необязательный # Переименовать метку. rename_to: second_name # необязательный # Разделитель, который нужно использовать между добавляемым префиксом и текущим значением метки. delimiter: . # необязательный, по умолчанию '.' ``` ## Фильтр transform_metric_labels {#transform_metric_labels_filter} Фильтр позволяет добавлять к метрикам новые метки, удалять и заменять существующие. В качестве значения метки можно указать фиксированную строку или текстовое выражение с использованием других меток. С помощью выражения `match` можно ограничить набор метрик, к которым применяется преобразование. Описание параметров: ```yaml - filter: plugin: transform_metric_labels config: # Ограничить применение фильтра только теми метриками, которые удовлетворяют данному условию. match: "{name=gauge-*}" # необязательный параметр, по умолчанию не задан, фильтр применяется ко всем метрикам # Описание преобразований меток в формате "имя метки: выражение". # Имя метки — метка, которой присваивается новое значение. # Выражение — текстовая строка с описанием нового значения. # В этой строке с помощью синтаксиса "{my_label}" можно ссылаться на текущие значения меток, # включая ту метку, которая изменяется в данный момент. В таком случае будет использовано ее предыдущее значение. # Преобразования выполняются в заданном порядке, в последующих выражениях # можно ссылаться на результаты предыдущих. # Синтаксис выражений аналогичен тому, который используется в фильтре assign. # С помощью {my_label|default_value} можно указать значение по умолчанию, если метка my_label не найдена. # Чтобы удалить метку, используйте синтаксис my_label: "-". labels: - l2: "prefix_{l1}_suffix" # обязательный - l3: "prefix2_{l2}_s_{l1|default_value}" # обязательный - l4: "-" # обязательный ``` Читайте также [описание синтаксиса запросов](../../querying.md#selectors).