Parsery

Deklarace parseru přijímá originální událost nebo konkrétní pole částečně parsované události jako vstup, analyzuje její jednotlivé části a ukládá je jako dvojice klíč-hodnota k události.

LogMan.io Parsec aktuálně podporuje tři typy deklarací parserů:

JSON parser
Windows Event parser
Parsec parser

Struktura deklarace

K určení typu deklarace je třeba specifikovat sekci define.

define:
  type: <declaration_type>

Pro deklaraci parseru specifikujte type jako parser.

JSON parser

JSON parser se používá pro parsování událostí (nebo částí událostí) se strukturou JSON.

parser_json.yaml

define:
  name: JSON parser
  type: parser/json
  field: <custom_field>
  target: <custom_target>

Když je specifikováno field, parsování se aplikuje na toto pole; výchozí je aplikovat to na originální událost.

Když je specifikováno target, parsed objekt se uloží do určeného cílového pole; výchozí je uložení s klíčem json. Vlastní cílové pole musí dodržovat regulární výraz json[0-9a-zA-Z] (začínající "json" následované jakýmkoliv alfanumerickým znakem).

Example

Následující originální událost se strukturou JSON je parsována JSON parserem s výchozím nastavením:

{
  "key": {
    "foo": 1,
    "bar": 2
  }
}

10_parser.yaml

define:
  name: JSON parser
  type: parser/json

Výsledná událost bude:

{
  "json": <JSON object>,
}

Následující událost obsahuje vnitřní část JSON, takže JSON parser může být aplikován na toto předparsované pole a výsledek bude uložen do vlastního pole jsonMessage:

<14>1 2023-05-03 15:06:12 {"key": {"foo": 1, "bar": 2}}

20_parser_message.yaml

define:
  name: JSON parser
  type: parser/json
  field: message
  target: jsonMessage

Výsledná událost bude:

{
  "log.syslog.priority": 14,
  "@timestamp": 140994182325993472,
  "message": "{"key": {"foo": 1, "bar": 2}}",
  "jsonMessage": <JSON object>
}

Windows Event parser

Windows Events parser se používá pro parsování událostí, které jsou produkovány Microsoft Windows. Tyto události jsou ve formátu XML.

define:
  name: Windows Events Parser
  type: parser/windows-event

Toto je kompletní Windows Event parser a bude parsovat události od Microsoft Windows, oddělující jednotlivá pole do dvojic klíč-hodnota.

Parsec parser

Parsec parser se používá pro parsování událostí v prostém textovém formátu. Je založen na SP-Lang Parsec expressions.

Pro parsování originálních událostí použijte následující deklaraci:

parser.yaml

define:
  name: My Parser
  type: parser/parsec

parse:
  !PARSE.KVLIST
    - ...
    - ...
    - ...

subparser.yaml

define:
  name: My Parser
  type: parser/parsec
  field: <custom_field>

parse:
  !PARSE.KVLIST
    - ...
    - ...
    - ...

Když je specifikováno field, parsování se aplikuje na toto pole, jinak se aplikuje na originální událost. Proto musí být přítomno v každém subparseru.

Typy specifikací field:

field: <custom_field> - pravidelné pole předparsované předchozím parserem.
field: json /key/foo - JSON klíč /key/foo z předparsovaného JSON objektu json. Název JSON objektu a JSON klíč musí být odděleny mezerou. JSON klíč vždy začíná "/", a každá další úroveň je oddělena znakem /.
JSON klíč se specifikovaným typem, výchozí typ je string.

field:
  json: /key/foo
  type: int

Příklady deklarací Parsec parseru

Příklad 1: Jednoduchý příklad

Pro účely příkladu, řekněme, že chceme parsovat sbírku jednoduchých událostí:

Ahoj Miroslave z Prahy!
Ahoj Kristýno z Plzně.

{
  "name": "Miroslav",
  "city": "Prague"
}

{
  "name": "Kristýna",
  "city": "Pilsen"
}

define:
  type: parser/parsec

parse:
  !PARSE.KVLIST
    - !PARSE.UNTIL " "
    - name: !PARSE.UNTIL " "
    - !PARSE.EXACTLY "from "
    - city: !PARSE.LETTERS

Příklad 2: Složitější příklad

Pro účely příkladu, řekněme, že chceme parsovat sbírku jednoduchých událostí:

Proces cleaning[123] skončil s kódem 0.
Proces log-rotation skončil s kódem 1.
Proces cleaning[657] začal.

A chceme výstup ve následujícím formátu:

{
  "process.name": "cleaning",
  "process.pid": 123,
  "event.action": "process-finished",
  "return.code": 0
}

{
  "process.name": "log-rotation",
  "event.action": "process-finished",
  "return.code": 1
}

{
  "process.name": "cleaning",
  "process.pid": 657,
  "event.action": "process-started"
}

Deklarace bude následující:

10_parser.yaml

define:
  type: parser/parsec

parse:
  !PARSE.KVLIST
    - !PARSE.UNTIL " "
    - !TRY
      - !PARSE.KVLIST
        - process.name: !PARSE.UNTIL "["
        - process.pid: !PARSE.UNTIL "]"
        - !PARSE.SPACE
      - !PARSE.KVLIST
        - process.name: !PARSE.UNTIL " "
    - !TRY
      - !PARSE.KVLIST
        - !PARSE.EXACTLY "started."
        - event.action: "process-started"
      - !PARSE.KVLIST
        - !PARSE.EXACTLY "finished with code "
        - event.action: "process-finished"
        - return.code: !PARSE.DIGITS

Příklad 3: Parsování syslog událostí

Pro účely příkladu, řekněme, že chceme parsovat jednoduchou událost ve formátu syslog:

<189> Sep 22 10:31:39 server-abc server-check[1234]: User "harry potter" logged in from 198.20.65.68

Chceme výstup ve následujícím formátu:

{
  "PRI": 189,
  "timestamp": 1695421899,
  "server": "server-abc",
  "process.name": "server-check",
  "process.pid": 1234,
  "user": "harry potter",
  "action": "log-in",
  "ip": "198.20.65.68"
}

Vytvoříme dva parsery. První parser bude parsovat záhlaví syslog a druhý bude parsovat zprávu.

10_parser.yaml

define:
  name: Syslog parser
  type: parser/parsec

parse:
  !PARSE.KVLIST
    - !PARSE.EXACTLY "<"
    - PRI: !PARSE.DIGITS
    - !PARSE.EXACTLY ">"

    - timestamp: ...
    - server: !PARSE.UNTIL " "
    - process.name: !PARSE.UNTIL "["
    - process.pid: !PARSE.UNTIL "]"
    - !PARSE.EXACTLY ":"
    - message: !PARSE.CHARS

Tento parser

20_parser_message.yaml

define:
  type: parser/parsec
  field: message
  drop: yes

parse:
  !PARSE.KVLIST
    - !PARSE.UNTIL " "
    - user: !PARSE.BETWEEN { what: '"' }
    - !PARSE.EXACTLY " "
    - !PARSE.UNTIL " "
    - !PARSE.UNTIL " "
    - !PARSE.UNTIL " "
    - ip: !PARSE.CHARS

Příklad 4: Parsování JSON událostí

Pro účely příkladu, řekněme, že chceme parsovat JSON událost:

{
  "data": {
    "action": "allow",
    "backendStatusCode": "200",
    "clientAddr": "89.183.114.162",
    "countryCode": "cz",
    "host": "www.praha.cz",
    "response": {
      "backendTime": "0.043",
      "code": "200"
    }
  },
  "time": "2024-03-03T01:15:03.480Z"
}

Vytvoříme dva parsery. První parser bude parsovat originální událost a uloží ji jako JSON objekt v poli json.

10_parser.yaml

define:
  type: parser/json

Výsledná událost bude:

{
  "json": <JSON object>
}

Další parser bude parsovat pole /time ze JSON objektu.

20_parser_timestamp.yaml

define:
  type: parser/parsec
  field: json /time

parse:
  !PARSE.KVLIST
  - "@timestamp": !PARSE.DATETIME
    - year: !PARSE.DIGITS
    - '-'
    - month: !PARSE.MONTH "number"
    - '-'
    - day: !PARSE.DIGITS
    - 'T'
    - hour: !PARSE.DIGITS
    - ':'
    - minute: !PARSE.DIGITS
    - ':'
    - second: !PARSE.DIGITS
    - microsecond: !PARSE.FRAC base: "micro"

Výsledná událost bude:

{
  "json": <JSON object>,
  "@timestamp": 140994182325993472
}