Lookup Manager

к сведению

Справочник (lookup) - это статическая таблица данных, которая используется для обогащения или преобразования данных во время поиска.

Модуль Lookup Manager отвечает за создание, просмотр, редактирование и удаление справочников, а также за управление значениями, содержащимися в них. Он обеспечивает централизованное управление справочными данными, используемыми в системе.

---

Список справочников

Для просмотра существующих справочников необходимо перейти в раздел Навигационное меню - Справочники. На странице отображается список справочников:

Таблица списка содержит следующие столбцы:

• Название справочника - название и теги справочника, при нажатии открывается редактор справочника
• Параметры - название индекса и перечень полей справочника
• Тип справочника - Системный или Пользовательский

Над таблицей расположены строка поиска, фильтр по тегам и фильтр по типу справочника. Кнопка Создать открывает мастер создания справочника.

Меню действий в конце каждой строки содержит следующие пункты:

• Теги - управление тегами справочника
• Редактировать - переход к редактированию справочника
• Разрешения - настройка прав доступа
• Открыть в поиске - открытие данных справочника на странице Поиск в новой вкладке
• Удалить - удаление справочника, недоступно для системных справочников

При выборе нескольких справочников с помощью флажков становятся доступны массовые операции: изменение тегов и разрешений (Редактировать выбранное), а также массовое удаление.

Обратите внимание!

Если в системе настроен коррелятор, на странице отображаются вкладки Список справочников и Активные списки. Работа с активными списками будет описана в отдельном разделе.

---

Создание справочника

Обратите внимание!

Рекомендуется присваивать индексам справочников названия, соответствующие названиям lookup.

Создание справочника выполняется с помощью мастера, в котором необходимо последовательно заполнить три шага. Для создания справочника необходимо:

1. Перейти в Список справочников и нажать кнопку Создать. Откроется мастер создания справочника

2. На шаге Имя справочника указать название конфигурации. Название может содержать только латинские буквы, цифры, дефисы и знаки подчеркивания без пробелов или разделителей

3. На шаге Исходный индекс ввести новое имя индекса или выбрать существующий индекс из списка

   

   Под полем отображается признак выбранного индекса: Существующий индекс или Новый индекс.

4. На шаге Поля определить перечень полей справочника. Содержимое шага зависит от того, какой индекс был указан на предыдущем шаге

   • для нового индекса необходимо добавить поля с помощью кнопки Добавить поле, указав название и тип каждого поля

     

     Доступны следующие типы полей: Строка, Целое число, Дробное число, Дата, Булево, IP-адрес. Подробнее о типах в разделе типы данных.

   • для существующего индекса необходимо выбрать поля из схемы индекса с помощью переключателей. Для каждого поля отображаются его тип и возможность сортировки

     

5. Нажать кнопку Продолжить. Дальнейшее поведение зависит от типа индекса

   • при выборе существующего индекса справочник будет создан сразу, откроется редактор с данными индекса

   • при создании нового индекса откроется пустая таблица редактора. Индекс и конфигурация справочника будут созданы после нажатия кнопки Сохранить

     

После создания справочник отобразится в общем списке.

---

Редактор справочника

Редактор открывается при нажатии на название справочника в списке и предназначен для просмотра и изменения данных и настроек справочника:

Данные загружаются с сервера постранично, поэтому редактор одинаково работает со справочниками любого объема.

Панель инструментов

В верхней части редактора расположены строка поиска и следующие кнопки:

• Скрытые столбцы - управление скрытыми столбцами, кнопка активна только при наличии скрытых столбцов
• Настройки справочника - открытие настроек справочника
• Отменить последнее действие / Повторить последнее действие - отмена и повтор изменений
• Экспорт - экспорт данных в CSV-файл
• Импорт - импорт данных из CSV-файла
• Открыть в поиске - открытие данных справочника на странице Поиск в новой вкладке
• Сохранить - сохранение всех накопленных изменений данных и конфигурации

Типы данных

Каждый столбец справочника имеет тип данных. Иконка типа отображается в заголовке столбца рядом с названием. Тип определяет форму ввода значения и доступные операции фильтрации:

Тип	Отображение	Форма ввода
Строка	текст	текстовое поле
Целое число	число с разделением разрядов	числовое поле
Дробное число	число с разделением разрядов	числовое поле
Дата	текстовое представление даты	текстовое поле, значение сохраняется без преобразования
Булево	переключатель	переключатель прямо в ячейке, без перехода в режим редактирования
IP-адрес	моноширинный текст	всплывающий редактор с выбором версии IPv4 / IPv6

Редактирование ячейки начинается двойным щелчком или нажатием Enter на выбранной ячейке. Редактор IP-адреса для версии IPv4 состоит из четырех сегментов с автоматическим переходом между ними:

Помимо перечисленных типов, ячейки типа Строка могут хранить массивы строк и массивы объектов. Элементы массива отображаются в ячейке отдельными значками, а редактирование выполняется в редакторе массивов.

Редактор массивов

Редактор массивов открывается двойным кликом по ячейке с массивом или с помощью пункта Редактировать как массив контекстного меню ячейки. Редактор содержит две вкладки: Список и JSON.

Вкладка Список для массива примитивных значений отображает список полей с возможностью перетаскивания элементов для изменения порядка:

Для массива объектов вкладка Список отображает таблицу, в которой можно редактировать значения, переименовывать и удалять столбцы, а также добавлять строки и столбцы:

Вкладка JSON позволяет редактировать массив в виде текста с подсветкой синтаксиса и проверкой корректности JSON:

Для пустого массива вкладка Список предлагает выбрать способ заполнения: Список значений или Таблица объектов.

Кнопка Применить переносит изменения в ячейку. Кнопка недоступна, если во вкладке JSON введен некорректный JSON.

Настройки справочника

Настройки открываются кнопкой Настройки справочника на панели инструментов редактора:

В настройках доступны следующие параметры:

• Название конфигурации и Название индекса - недоступны для изменения после создания справочника, значения можно скопировать в буфер обмена
• Поле сортировки по умолчанию - поле, по которому сортируется таблица, если сортировка не задана
• раздел Правила совпадения - параметры Условие, Лимит и Максимальное количество соответствий
• раздел Правила полей - перечни полей Чувствительность к регистру, Wildcard и Cidrmatch

Описание параметров приведено в разделе структура конфигурации.

Обратите внимание!

Изменения настроек применяются только после нажатия кнопки Сохранить на панели инструментов. При наличии несохраненных изменений конфигурации на кнопке настроек отображается красный индикатор, а в самих настройках - предупреждение Изменения еще не сохранены.

Работа со строками

Основные операции со строками выполняются через контекстное меню, которое открывается щелчком правой кнопки мыши по ячейке:

Доступны следующие пункты:

• Копировать - копирование выделенных ячеек в буфер обмена
• Вставить - вставка содержимого буфера обмена в выделенную область
• Вставить выше / Вставить ниже - вставка содержимого буфера обмена в виде новых строк, существующие данные не перезаписываются
• Добавить выше / Добавить ниже - добавление новой пустой строки
• Очистить - очистка значений выделенных ячеек
• Редактировать как массив - открытие редактора массивов

Пункты, недоступные в текущем контексте, скрываются. Например, пункты вставки не отображаются при пустом буфере обмена.

При щелчке правой кнопки мыши по столбцу с номерами строк меню содержит пункт Удалить, который удаляет выделенные строки.

Если справочник пуст, добавить первую строку можно кнопкой Добавить новую строчку в центре таблицы.

Работа со столбцами

Операции со столбцами выполняются через контекстное меню, которое открывается щелчком правой кнопки мыши по заголовку столбца:

Доступны следующие пункты:

• Добавить справа / Добавить слева - добавление нового столбца. В появившемся модальном окне необходимо указать название и тип поля

  

• Удалить - удаление столбца. Поле убирается только из конфигурации справочника, данные в индексе физически сохраняются: при создании столбца с тем же именем и типом значения снова отобразятся в таблице

• Настроить - настройка нового (еще не сохраненного) столбца: переименование и изменение типа

• Закрепить / Открепить - закрепление столбца у левого края таблицы

• Скрыть - скрытие столбца

• Сбросить порядок - возврат исходного порядка столбцов

Ширину столбца можно изменять, перетаскивая границу заголовка, а порядок столбцов - перетаскиванием самих заголовков. Ширина, порядок и видимость столбцов сохраняются в браузере пользователя.

Скрытые столбцы отображаются в списке по кнопке Скрытые столбцы на панели инструментов. Показать столбец можно по отдельности или все сразу кнопкой Показать все:

Выделение и буфер обмена

Таблица поддерживает выделение отдельных ячеек и диапазонов:

• выделение диапазона - перетаскивание курсора при зажатой левой кнопке мыши
• Shift + клик - выделение диапазона от текущей ячейки
• Ctrl/Cmd + клик - добавление или исключение отдельных ячеек
• клик по столбцу с номерами строк - выделение всей строки

Копирование выполняется в формате TSV, поэтому данные можно переносить между справочником и табличными редакторами, например Excel. Вставка из буфера обмена работает в двух режимах:

• вставка от опорной ячейки - применяется, если выделенная область меньше содержимого буфера обмена. Данные раскладываются вправо и вниз от верхней левой ячейки выделения. При нехватке строк таблица автоматически расширяется новыми строками
• диапазонная вставка - применяется, если выделенная область не меньше содержимого буфера обмена. Значения вставляются в пределах выделенной области, начиная с ее верхней левой ячейки

После вставки затронутая область автоматически выделяется. Для вставки данных новыми строками без перезаписи существующих используйте пункты Вставить выше / Вставить ниже контекстного меню.

Быстрые клавиши

Операция	Сочетание клавиш		Описание
	Windows	Mac
Выделение всех	Ctrl + A	Cmd + A	Выделяет все заголовки и ячейки данных
Копирование	Ctrl + C	Cmd + C	Копирует выделенные ячейки в формате TSV
Вставка	Ctrl + V	Cmd + V	Вставляет содержимое буфера обмена в текущий диапазон
Очистка	Delete / Backspace		Удаляет содержимое выделенных ячеек
Отмена действия	Ctrl + Z	Cmd + Z	Отменяет последнее изменение
Снятие выделения	Esc		Снимает выделение ячеек

Подсветка изменений

Все изменения накапливаются в черновике и применяются только после нажатия кнопки Сохранить. До сохранения измененные данные подсвечиваются в таблице:

• зеленым - новые строки
• желтым - измененные ячейки
• красным - ячейки со значениями, не соответствующими типу столбца. При наведении курсора отображается текст ошибки

Обратите внимание!

Пока в таблице есть некорректные значения, кнопка Сохранить недоступна.

Отмена и повтор действий

Кнопки Отменить последнее действие и Повторить последнее действие на панели инструментов работают со всеми несохраненными изменениями: редактированием ячеек, добавлением и удалением строк и столбцов, вставкой из буфера обмена и изменениями настроек.

При попытке покинуть страницу с несохраненными изменениями отображается предупреждение:

Сортировка и фильтрация

Сортировка включается кликом по заголовку столбца и переключается циклически: по возрастанию, по убыванию, без сортировки. Одновременно таблица сортируется только по одному столбцу. Если сортировка не задана, применяется Поле сортировки по умолчанию из настроек справочника.

Фильтр столбца открывается кнопкой с изображением воронки в заголовке:

Набор операций фильтра зависит от типа данных столбца:

• текстовые поля: Равно, Не равно, Начинается с, Содержит, Не содержит, Заканчивается на, Пусто, Не пусто
• числовые поля: Равно, Не равно, Больше, Больше или равно, Меньше, Меньше или равно, В диапазоне, Пусто, Не пусто
• поля IP-адресов: Равно, Не равно, Пусто, Не пусто. В качестве значения можно указать точный IP-адрес или подсеть в формате CIDR, например 192.168.0.1/24

В одном фильтре можно объединить до 10 условий с помощью логических операторов И / ИЛИ. Кнопка Сбросить очищает фильтр текущего столбца.

к сведению

Сортировка, фильтрация и поиск выполняются на сервере по всем данным справочника, а не только по загруженной странице.

Навигация по страницам

В нижней части редактора расположена панель навигации:

Кнопка Строк на странице позволяет выбрать количество строк на странице: 50, 100, 250, 500 или 1000 строк. Поле Перейти к странице выполняет переход к произвольной странице по ее номеру.

Хранилище данных ограничивает глубину перехода: за один запрос можно пропустить не более 100 000 строк от начала, от конца или от текущей позиции. При попытке перейти к странице за пределами лимита отображается предупреждение с предложением выполнить переход в несколько шагов:

---

Поиск

Поиск поддерживает сопоставление по правилу wildcard. Условия совпадения, которые указываются в настройках справочника, не влияют на результат поиска. Поисковый запрос вводится в строке поиска на панели инструментов и применяется нажатием Enter. Все приведенные ниже примеры будут рассматриваться на следующем справочнике:

Простое условие

Поиск в справочнике можно осуществлять простым условием по:

1. Конкретному полю, как показано в примере

2. Значению, которое может находиться в любом поле, как показано в примере

Составное условие

Поиск в справочнике можно осуществлять составным условием по:

1. Конкретным полям, как показано в примере

2. Значениям, которые могут находиться в любом поле, как показано в примере

---

Добавление данных

Добавить данные можно несколькими способами:

1. Создать и заполнить строки вручную. Работа со строками описана в разделе работа со строками

2. Добавить существующие данные в справочник с помощью команды outputlookup

   Обратите внимание!

   Этот способ может перезаписать поля и удалить прежние данные. Это происходит, если параметр append команды outputlookup имеет значение false. В противном случае новые данные добавляются к существующим.

3. Импортировать CSV-файл в справочник. Для импорта данных необходимо нажать кнопку Импорт на панели инструментов редактора. После нажатия появится модальное окно

   

   В окне импорта нажмите Выберите .csv файл, выберите CSV-файл и нажмите Импорт. Новые записи добавляются к существующим данным. Разделитель определяется автоматически по строке заголовка файла.

   Особенности импорта:

   • размер файла не ограничен: данные считываются и отправляются на сервер частями, во время загрузки отображается прогресс
   • переключатель Объединить колонки из .csv-документа добавляет в справочник столбцы из заголовка файла, которых еще нет в конфигурации
   • прерванную загрузку можно возобновить: при повторном выборе того же файла появится предложение продолжить с места остановки (Продолжить) или начать заново (Начать заново)

4. Дополнить индекс справочника новыми данными через Консоль разработчика. После добавления новых записей изменения сохраняются автоматически

---

Экспорт данных

Кнопка Экспорт на панели инструментов выгружает данные справочника с учетом несохраненных изменений в файл <название справочника>.csv.

---

Структура конфигурации

Название	Поле в индексе	Синтаксис	Описание	Пример данных
Название конфигурации	name	<string>	Название справочника, которое нельзя изменить после создания	lookup_name
Название индекса	idx	<string>	Название индекса, соответствующего справочнику. Название нельзя изменить после создания	index_name
Поля	fields	<array>	Перечень полей справочника, которые используются для обогащения. Полями можно управлять через столбцы таблицы в редакторе	field1, field2
Поле сортировки по умолчанию	default_sort_field	<string>	Поле, по которому таблица сортируется по возрастанию, если сортировка не задана	field1
Чувствительность к регистру	case_sensitive	<array>	Перечень полей из справочника, которые чувствительны к регистру при совпадении	field1, field2
Wildcard	wildcards	<array>	Перечень полей справочника, для которых используется сопоставление по правилу Wildcard	field1, field2
Cidrmatch	cidrmatch	<array>	Перечень полей справочника, для которых используется сопоставление по правилу Cidrmatch	field1, field2
Условие	condition	<string>	Условие фильтрации, применяемое перед сопоставлением записей справочника	status != "Уволен"
Лимит	limit	<int>	Ограничение размера справочных данных перед сопоставлением	1000
Максимальное количество соответствий	max_match	<int>	Максимальное количество совпадений из справочника на один результат поиска при выполнении команды lookup	100

Параметры Название конфигурации и Название индекса задаются при создании справочника, остальные параметры доступны в настройках справочника на странице редактора.

---

Примеры сопоставления полей

Во всех приведенных ниже примерах используется команда lookup для дополнения исходных событий данными из справочника.

Общие правила

В подразделе приведены примеры сопоставления без специальных правил: значение поля справочника полностью совпадает со значением соответствующего поля события. Во всех примерах используется следующий справочник:

Пример сопоставления одной строки справочника

Если сопоставлена одна строка справочника, исходное событие дополняется ее данными:

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="8.9.2"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие дополнено полями agent.id, agent.name и host.os с соответствующими значениями строки справочника.

Пример сопоставления нескольких строк справочника

Если сопоставлено несколько строк справочника, результирующие поля преобразуются в массивы значений из соответствующих строк:

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="8.9.0"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие дополнено полями agent.id, agent.name и host.os с массивами значений из соответствующих строк.

Пример отсутствия сопоставления в справочнике

Если поля справочника не сопоставлены, событие не дополняется данными:

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="7.5.5"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие не было дополнено полями agent.id, agent.name и host.os, так как в справочнике отсутствует поле agent.version с необходимым значением.

Пример сопоставления нескольких полей из справочника

Команда lookup позволяет сопоставлять несколько полей, чтобы точнее определить события для дополнения данными:

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="8.9.0", agent.name="winlogbeat_6"
| lookup agents_info agent.version, agent.name OUTPUT agent.id, host.os

Результат выполнения будет следующим:

Обратите внимание!

В примере сопоставления нескольких строк поиск только по agent.version дополняет событие данными из нескольких строк. Поскольку в данном случае сопоставляются поля agent.version и agent.name, событие дополняется только данными строки winlogbeat_6.

Использование чувствительного к регистру поля

В настройках справочника можно указать поля, чувствительные к регистру. В примере используется справочник из раздела общие правила, в котором поле agent.name чувствительно к регистру.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.name="WinLogBeat_1"
| lookup agents_info agent.name OUTPUT agent.id, agent.version, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие не дополнено данными из строки справочника, в которой agent.name имеет значение winlogbeat_1.

Если бы поле agent.name не было чувствительно к регистру, результат был бы следующим:

Обратите внимание!

Событие дополнено данными из строки справочника, в которой agent.name имеет значение winlogbeat_1.

Wildcard

В настройках справочника можно указать поля, которые будут сопоставляться по правилу Wildcard.

Обратите внимание!

Значения указанного поля должны соответствовать правилу wildcard.

Пример №1

Справочник для первого примера:

Обратите внимание!

Поле agent.version сопоставляется по принципу wildcard.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="4.6.5"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие было дополнено полями agent.id, agent.name и host.os с соответствующими значениями строки из справочника.

Пример №2

Справочник для второго примера:

Обратите внимание!

Поле agent.name сопоставляется по принципу wildcard.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.name="filebeat_1"
| lookup agents_info agent.name OUTPUT host.os, agent.version, agent.id

Результат выполнения будет следующим:

Обратите внимание!

Событие было дополнено полями host.os, agent.version и agent.id с массивом значений из соответствующих строк.

Пример №3

Справочник для третьего примера:

Обратите внимание!

Поле agent.version сопоставляется по принципу wildcard.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="9.6.0"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие не было дополнено полями agent.id, agent.name и host.os, так как в справочнике отсутствует поле agent.version с необходимым wildcard-значением.

Cidrmatch

В настройках справочника можно указать поля, которые будут сопоставляться по правилу Cidrmatch.

Обратите внимание!

Значения указанного поля должны соответствовать правилу cidrmatch.

Во всех примерах используется следующий справочник:

Обратите внимание!

Поле host.netmask сопоставляется по принципу cidrmatch.

Пример №1

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval host.ip="25.22.8.3"
| lookup agents_info host.netmask AS host.ip OUTPUT agent.id, agent.name, host.os, agent.version, host.netmask

Результат выполнения будет следующим:

Обратите внимание!

Событие было дополнено полями agent.id, agent.name, host.os, agent.version и host.netmask с соответствующими значениями строки из справочника.

Пример №2

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval host.ip="192.168.16.8"
| lookup agents_info host.netmask AS host.ip OUTPUT agent.id, agent.name, host.os, agent.version, host.netmask

Результат выполнения будет следующим:

Обратите внимание!

Событие было дополнено полями agent.id, agent.name, host.os, agent.version и host.netmask с массивом значений из соответствующих строк.

Пример №3

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval host.ip="32.16.8.5"
| lookup agents_info host.netmask AS host.ip OUTPUT agent.id, agent.name, host.os, agent.version, host.netmask

Результат выполнения будет следующим:

Обратите внимание!

Событие не было дополнено полями agent.id, agent.name, host.os, agent.version и host.netmask, так как в справочнике отсутствует поле host.netmask с необходимым cidrmatch-значением.

Условия

В настройках справочника можно указать условия сопоставления. Условие задается в поле Условие раздела Правила совпадения. В примерах используется справочник из раздела общие правила.

Пример №1

Укажем следующее условие в настройках справочника:

При обращении к строке, в которой agent.name имеет значение winlogbeat_7, исходное событие не будет дополнено данными.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.name="winlogbeat_7"
| lookup agents_info agent.name OUTPUT agent.id, host.os, agent.version

Результат выполнения будет следующим:

Обратите внимание!

Событие не дополнено полями agent.id, host.os и agent.version, поскольку значение winlogbeat_7 в поле agent.name противоречит условию справочника.

Пример №2

В настройках справочника укажем условие из предыдущего примера.

При выполнении следующего запроса:

| makeresults 
| fields - @timestamp
| eval agent.version="8.9.0"
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os, agent.version

Результат выполнения будет следующим:

Обратите внимание!

Событие не было дополнено полями agent.id, agent.name, host.os и agent.version, где agent.name не является winlogbeat_7.

Пример №3

Укажем следующее условие в настройках справочника:

При выполнении следующего запроса:

source logs
| lookup agents_info agent.version OUTPUT agent.id, agent.name, host.os

Результат выполнения будет следующим:

Обратите внимание!

Событие дополнено полями agent.id, agent.name и host.os, поскольку оно соответствует условию справочника: agent.version имеет значение 8.9.0, а host.os - Windows.

примечание

Событие не дополнено полями agent.id, agent.name и host.os, поскольку значение Linux в поле host.os противоречит условию справочника.

---

Удаление справочника

Для удаления справочника необходимо в списке справочников открыть меню действий строки и выбрать пункт Удалить. Появится окно подтверждения:

По умолчанию удаляется только конфигурация справочника. Переключатель Также удалить хранилище (индекс с данными) дополнительно удаляет индекс вместе с данными.

Для удаления нескольких справочников выберите их с помощью флажков в списке и нажмите кнопку массового удаления.

Обратите внимание!

Удаленный справочник нельзя восстановить.