Команды обработки логов: различия между версиями

Материал из Документация Ключ-АСТРОМ
← Предыдущая правка
ВизуальныйВики-текст
Нет описания правки
 
Строка 1: Строка 1:
Команды обработки логов и событий представляют собой операторы и предложения DQL. Определение правила позволяет определить последовательность команд для достижения желаемой цели правила обработки.


Определение правила обработки состоит из последовательности команд обработки слева направо, соединенных вместе с помощью символа вертикальной черты (<code>|</code>). Концептуально это похоже на конвейеризацию команд Unix, где вывод команды слева от вертикальной черты становится вводом команды справа от вертикальной черты. Конвейер всегда должен начинаться с команды, создающей структурированный поток данных для последующих команд.
= Команды обработки логов =
Команды обработки логов и событий представляют собой операторы и предложения '''DQL'''. Определение правила позволяет задать последовательность команд для достижения нужной цели правила обработки. Определение правила обработки состоит из последовательности команд обработки, соединённых слева направо символом вертикальной черты (<code>|</code>). Концептуально это похоже на конвейер команд Unix, где вывод команды слева от символа <code>|</code> становится вводом для команды справа. Пайплайн всегда должен начинаться с команды, создающей структурированный поток данных для последующих команд.


=== PARSE ===
== PARSE ==
Команда <code>PARSE</code> анализирует выбранное поле с помощью предоставленного выражения шаблона (Ключ-АСРОМ Pattern Language), дополняя запись лога экспортированными значениями.
Команда <code>PARSE</code> разбирает выбранное поле с помощью заданного выражения-шаблона ('''Язык шаблонов Ключ-АСТРОМ'''), дополняя запись лога экспортированными значениями.


==== Примеры: ====
=== Примеры ===


* Анализ атрибутов из разных форматов в рамках одного шаблонного выражения.
== USING ==
* Выделение определенных полей из содержимого JSON.
Команда <code>USING</code> задаёт входные данные для данной трансформации, перечисляя поля с опциями, которые могут быть переданы из входящего события в трансформацию. Эта команда должна быть первой командой, используемой в определении процессора.


=== USING ===
'''Формат объявления полей:''' <code>USING(<field_expression>, <field_expression>, ...)</code>
Команда USING определяет входные данные для данного преобразования, перечисляя поля с параметрами, которые могут быть переданы из входящего события в преобразование. Эта команда должна быть первой командой, используемой в определении процессора.


Формат объявления полей: <code>USING(<field_expression>, <field_expression>, ...)</code>
'''Формат выражения поля:''' <code>[IN|INOUT] name: [type[]?]</code>


Формат выражения поля: <code>[IN|INOUT] name: [type[]?]</code>
Команда <code>USING</code> в определении процессора эквивалентна оператору <code>USING(IN content:STRING)</code>.


Команда <code>USING</code> в определении процессора является эквивалентом <code>USING(IN content:STRING)</code> оператора.
'''Опции:'''


Параметры:
* <code>IN</code> — поле только для чтения, опция по умолчанию.
* <code>INOUT</code> — записываемое поле.
* <code>type</code> — один из следующих типов: <code>STRING</code>, <code>BOOLEAN</code>, <code>INTEGER</code>, <code>LONG</code>, <code>DOUBLE</code>, <code>DURATION</code>, <code>TIMESTAMP</code>, <code>IPADDR</code>.
* <code>[]</code> — помечает поле как массив, что означает, что будет передано несколько значений атрибута.
* <code>?</code> — помечает поле как необязательное, что означает, что трансформация будет выполнена, даже если такого атрибута нет в событии.


* <code>IN</code>— поле только для чтения, опция по умолчанию.
'''Пример:''' <code>USING(content, event.type:STRING?, INOUT attribute:INT[]) | ...</code>
* <code>INOUT</code>— записываемое поле.
* <code>type</code>—один из следующих типов: <code>STRING</code>, <code>BOOLEAN</code>, <code>INTEGER</code>, <code>LONG</code>, <code>DOUBLE</code>, <code>DURATION</code>, <code>TIMESTAMP</code>, <code>IPADDR</code>.
* <code>[]</code>— помечает поле как массив, что означает, что будет передано несколько значений атрибута.
* <code>?</code>— помечает поле как необязательное, что означает, что преобразование будет выполнено даже если в событии нет такого атрибута.


Пример:
В этом случае три поля передаются из входящего события в трансформацию:
{| class="wikitable"
|<nowiki>USING(content, event.type:STRING?, INOUT attribute:INT[]) | ...</nowiki>
|}
 
 
В этом случае из входящего события в преобразование передаются три поля:
 
<code>content</code>— строковое поле, доступное только для чтения
 
<code>event.type</code>; — необязательная строка, доступная только для чтения
 
<code>attribute</code>; — записываемый массив целых чисел.
 
=== FIELDS_ADD ===
Команда <code>FIELDS_ADD</code> указывает разделенный запятыми список литералов, функций, имен полей и выражений, которые необходимо вычислить.
 
Формат:
{| class="wikitable"
|FIELDS_ADD( [ alias':' ]
        { *
 
          | alias.*
 
          | '@'position
 
          | function
 
          | expression
 
          | literal
 
        }


        [ , ... ]
* <code>content</code> — строковое поле только для чтения
* <code>event.type</code> — необязательное строковое поле только для чтения
* <code>attribute</code> — записываемый массив целых чисел


)
== FIELDS_ADD ==
|}
Команда <code>FIELDS_ADD</code> задаёт разделённый запятыми список литералов, функций, имён полей и выражений для вычисления.


'''Формат:''' <code>FIELDS_ADD( [ alias':' ] { * | alias.* | '@'position | function | expression | literal } [ , ... ])</code>


Каждое выражение можно переименовать с помощью псевдонима. Псевдонимы, определенные в команде select, можно использовать в следующих командах по конвейеру.
Каждое выражение можно переименовать с помощью псевдонима. Псевдонимы, определённые в команде select, можно использовать в последующих командах пайплайна.


==== Пример: ====
=== Пример ===
В следующем примере мы вычисляем сумму <code>field1</code>и <code>field2</code>и помещаем результат в поле с именем <code>mySum</code>.
В следующем примере мы вычисляем сумму <code>field1</code> и <code>field2</code> и помещаем результат в поле с именем <code>mySum</code>.
{| class="wikitable"
{| class="wikitable"
|<code>field1</code>
!field1
|<code>field2</code>
!field2
|-
|-
|300
|300
|650
|650
|}
|}
<code>FIELDS_ADD(mySum:(field1 + field2))</code>
{| class="wikitable"
{| class="wikitable"
|FIELDS_ADD(mySum:(field1 + field2))
!field1
|}
!field2
{| class="wikitable"
!mySum
|<code>field1</code>
|<code>field2</code>
|<code>mySum</code>
|-
|-
|300
|300
Строка 92: Строка 60:
|}
|}


=== FIELDS_RENAME ===
== FIELDS_RENAME ==
Команда <code>FIELDS_RENAME</code> переименовывает указанные поля записи. Она сохраняет порядок полей и другие поля.
Команда <code>FIELDS_RENAME</code> переименовывает указанные поля записи. Она сохраняет порядок полей и другие поля.


Формат: <code>FIELDS_RENAME(newName:field, name2:field2, ...)</code>
'''Формат:''' <code>FIELDS_RENAME(newName:field, name2:field2, ...)</code>


==== Пример: ====
=== Пример ===
В следующем примере мы переименовываем поле <code>ip</code> в <code>src_addr</code> и переименовываем поле <code>f</code> в <code>value</code>.
В следующем примере мы переименовываем поле <code>ip</code> в <code>src_addr</code>, а поле <code>f</code> — в <code>value</code>.
{| class="wikitable"
{| class="wikitable"
|t
!t
|ip
!ip
|s
!s
|f
!f
|-
|-
|2020-09-23 15:14:42.947 +0300
|2020-09-23 15:14:42.947 +0300
Строка 110: Строка 78:
|0.0
|0.0
|}
|}
<code>FIELDS_RENAME(src_addr:ip, value:f)</code>
{| class="wikitable"
{| class="wikitable"
|FIELDS_RENAME(src_addr:ip, value:f)
!t
|}
!src_addr
{| class="wikitable"
!s
|t
!value
|src_addr
|s
|value
|-
|-
|2020-09-23 15:14:42.947 +0300
|2020-09-23 15:14:42.947 +0300
Строка 125: Строка 91:
|}
|}


=== FIELDS_REMOV ===
== FIELDS_REMOVE ==
Команда <code>FIELDS_REMOVE</code> удаляет указанные поля из выходного потока. Команда полезна в скриптах, удаляющих чувствительные поля.
Команда <code>FIELDS_REMOVE</code> удаляет указанные поля из выходного потока. Команда полезна в сценариях, исключающих конфиденциальные поля.
 
'''Формат:''' <code>FIELDS_REMOVE(field, field, ...)</code>


Формат: <code>FIELDS_REMOVE(field, field, ...)</code>
=== Пример ===
В следующем примере мы добавляем поля <code>t</code>, <code>ip</code>, <code>s</code> и <code>f</code>. Затем мы удаляем поля <code>s</code> и <code>ip</code>, оставляя нам поля <code>t</code> и <code>f</code>.


==== Пример: ====
<code>FIELDS_REMOVE(s, ip)</code>
В следующем примере мы добавляем поля <code>t</code>, <code>ip</code> и <code>s</code>, <code>f</code>. Затем мы удаляем поля <code>s</code> и <code>ip</code>, оставляя нам поля <code>t</code> и <code>f</code>.
{| class="wikitable"
{| class="wikitable"
|FIELDS_REMOVE(s, ip)
!t
|}
!f
{| class="wikitable"
|t
|f
|-
|-
|2020-09-23 15:17:39.497 +0300
|2020-09-23 15:17:39.497 +0300
Строка 149: Строка 114:
|}
|}


=== FILTER_OUT ===
== FILTER_OUT ==
Команда <code>FILTER_OUT</code> отбрасывает всю запись, используя выражение, возвращающее логическое значение (boolean_expression). Это команда отрицательного фильтра. Она может состоять из нескольких логических выражений, объединенных с помощью операторов AND, OR и NOT. Если условие выполнено, вся запись отбрасывается и не будет передана на следующий этап. Например, вы можете отбросить все записи с атрибутом уровня лога <code>DEBUG</code> или <code>debug</code>.
Команда <code>FILTER_OUT</code> отбрасывает всю запись, используя выражение, возвращающее логическое значение (<code>boolean_expression</code>). Это команда отрицательной фильтрации. Она может состоять из нескольких логических выражений, объединённых операторами <code>AND</code>, <code>OR</code> и <code>NOT</code>. Если условие выполнено, вся запись отбрасывается и не передаётся на следующую стадию.
 
Например, можно отбросить все записи с уровнем лога <code>DEBUG</code> или <code>debug</code>.
 
'''Формат:''' <code>FILTER_OUT(loglevel IN ['DEBUG', 'debug'])</code>
 
=== Примеры ===
 
* В следующем примере мы отбрасываем записи, где <code>_raw_text</code> (исходный текст необработанной записи) содержит строку <code>vpns</code> или <code>_raw_text</code> равно NULL:
 
<code>FILTER_OUT(contains(_raw_text, '/vpns/'))</code>
 
* В следующем примере мы отбрасываем записи, где строковое поле <code>type</code> равно <code>logout</code> или <code>type</code> равно NULL:


Формат: <code>FILTER_OUT(loglevel IN ['DEBUG', 'debug'])</code>
<code>FILTER_OUT(type = 'logout')</code>


==== Примеры: ====
* В следующем примере мы отбрасываем записи, где поле временной метки <code>last_modified</code> больше 7 дней назад или <code>last_modified</code> равно NULL:


* В следующем примере мы отбрасываем записи, в которых <code>_raw_text</code> (исходный необработанный текст записи) содержит строку <code>vpns</code> или <code>_raw_text</code> является <code>NULL</code>  <br />{| class="wikitable" |FILTER_OUT(contains(_raw_text, '/vpns/')) |}
<code>FILTER_OUT(last_modified >= now()[-7 day])</code>
* В следующем примере мы отбрасываем записи, где тип строкового поля равен <code>logout</code> или тип равен <code>NULL</code>  <br />{| class="wikitable" |FILTER_OUT(type = 'logout') |}
* В следующем примере мы отбрасываем записи, в которых поле временной метки <code>last_modified</code> больше 7 дней назад или <code>last_modified</code> равно <code>NULL</code>  <br />{| class="wikitable" |FILTER_OUT(last_modified >= now()[-7 day]) |}

Текущая версия от 18:21, 13 октября 2026

Команды обработки логов

Команды обработки логов и событий представляют собой операторы и предложения DQL. Определение правила позволяет задать последовательность команд для достижения нужной цели правила обработки. Определение правила обработки состоит из последовательности команд обработки, соединённых слева направо символом вертикальной черты (|). Концептуально это похоже на конвейер команд Unix, где вывод команды слева от символа | становится вводом для команды справа. Пайплайн всегда должен начинаться с команды, создающей структурированный поток данных для последующих команд.

PARSE

Команда PARSE разбирает выбранное поле с помощью заданного выражения-шаблона (Язык шаблонов Ключ-АСТРОМ), дополняя запись лога экспортированными значениями.

Примеры

USING

Команда USING задаёт входные данные для данной трансформации, перечисляя поля с опциями, которые могут быть переданы из входящего события в трансформацию. Эта команда должна быть первой командой, используемой в определении процессора.

Формат объявления полей: USING(<field_expression>, <field_expression>, ...)

Формат выражения поля: [IN|INOUT] name: [type[]?]

Команда USING в определении процессора эквивалентна оператору USING(IN content:STRING).

Опции:

  • IN — поле только для чтения, опция по умолчанию.
  • INOUT — записываемое поле.
  • type — один из следующих типов: STRING, BOOLEAN, INTEGER, LONG, DOUBLE, DURATION, TIMESTAMP, IPADDR.
  • [] — помечает поле как массив, что означает, что будет передано несколько значений атрибута.
  • ? — помечает поле как необязательное, что означает, что трансформация будет выполнена, даже если такого атрибута нет в событии.

Пример: USING(content, event.type:STRING?, INOUT attribute:INT[]) | ...

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

  • content — строковое поле только для чтения
  • event.type — необязательное строковое поле только для чтения
  • attribute — записываемый массив целых чисел

FIELDS_ADD

Команда FIELDS_ADD задаёт разделённый запятыми список литералов, функций, имён полей и выражений для вычисления.

Формат: FIELDS_ADD( [ alias':' ] { * | alias.* | '@'position | function | expression | literal } [ , ... ])

Каждое выражение можно переименовать с помощью псевдонима. Псевдонимы, определённые в команде select, можно использовать в последующих командах пайплайна.

Пример

В следующем примере мы вычисляем сумму field1 и field2 и помещаем результат в поле с именем mySum.

field1 field2
300 650

FIELDS_ADD(mySum:(field1 + field2))

field1 field2 mySum
300 650 950

FIELDS_RENAME

Команда FIELDS_RENAME переименовывает указанные поля записи. Она сохраняет порядок полей и другие поля.

Формат: FIELDS_RENAME(newName:field, name2:field2, ...)

Пример

В следующем примере мы переименовываем поле ip в src_addr, а поле f — в value.

t ip s f
2020-09-23 15:14:42.947 +0300 0.0.0.0 0ho0 0.0

FIELDS_RENAME(src_addr:ip, value:f)

t src_addr s value
2020-09-23 15:14:42.947 +0300 0.0.0.0 0ho0 0.0

FIELDS_REMOVE

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

Формат: FIELDS_REMOVE(field, field, ...)

Пример

В следующем примере мы добавляем поля t, ip, s и f. Затем мы удаляем поля s и ip, оставляя нам поля t и f.

FIELDS_REMOVE(s, ip)

t f
2020-09-23 15:17:39.497 +0300 0.0
2020-09-23 15:17:39.498 +0300 1.0
2020-09-23 15:17:39.499 +0300 2.0

FILTER_OUT

Команда FILTER_OUT отбрасывает всю запись, используя выражение, возвращающее логическое значение (boolean_expression). Это команда отрицательной фильтрации. Она может состоять из нескольких логических выражений, объединённых операторами AND, OR и NOT. Если условие выполнено, вся запись отбрасывается и не передаётся на следующую стадию.

Например, можно отбросить все записи с уровнем лога DEBUG или debug.

Формат: FILTER_OUT(loglevel IN ['DEBUG', 'debug'])

Примеры

  • В следующем примере мы отбрасываем записи, где _raw_text (исходный текст необработанной записи) содержит строку vpns или _raw_text равно NULL:

FILTER_OUT(contains(_raw_text, '/vpns/'))

  • В следующем примере мы отбрасываем записи, где строковое поле type равно logout или type равно NULL:

FILTER_OUT(type = 'logout')

  • В следующем примере мы отбрасываем записи, где поле временной метки last_modified больше 7 дней назад или last_modified равно NULL:

FILTER_OUT(last_modified >= now()[-7 day])

Источник — https://doc.ruscomtech.ru/index.php?title=Команды_обработки_логов&oldid=7046