evtctxadd

入力データが条件式と一致した場合に、指定したトピックとキーでイベントコンテキストを生成します。同じキーのイベントコンテキストがすでに存在する場合はタイムアウトを延長します。

コマンドプロパティ

項目説明
コマンドタイプ変換クエリ
必要な権限なし
ライセンス使用量対象外
並列実行対応
分散実行データノードで実行（mapper）

構文

evtctxadd [topic=STR] [key=STR] [expire=INT{s|m|h|d|mon}] [timeout=INT{s|m|h|d|mon}] [maxrows=INT] [logtick=STR] [dynamic=BOOL] EXPR

オプション

topic=STR
イベントトピック名。他のルールのイベントと区別するために一意の名前を付けます。dynamic=tの場合このオプションは無視されます。
key=STR
イベントコンテキストを識別するキー値を抽出するフィールド名。dynamic=tの場合このオプションは無視されます。
expire=INT{s|m|h|d|mon}
有効期限。イベントコンテキストが生成されてから指定した時間が経過するとイベントコンテキストが削除されます。条件式に一致する入力データが追加で入力されても有効期限は延長されません。dynamic=tの場合このオプションは無視されます。
  • s: 秒
  • m: 分
  • h: 時
  • d: 日
  • mon: 月
timeout=INT{s|m|h|d|mon}
タイムアウト。最後に条件に一致するイベントを受信してから指定した時間が経過するとイベントコンテキストが削除されます。条件式に一致する入力データが追加で入力されるとタイムアウトが延長されます。dynamic=tの場合このオプションは無視されます。
  • s: 秒
  • m: 分
  • h: 時
  • d: 日
  • mon: 月
maxrows=INT
イベントコンテキストに保存する最大行数。dynamic=tの場合このオプションは無視されます。（デフォルト: 10）
logtick=STR
外部時計ホストフィールド名。指定すると入力レコードの該当フィールドからホスト名を抽出し、_timeフィールドの時間を基準にイベント時計を進めます。
dynamic=BOOL
tを指定するとtopic、key、expire、timeout、maxrowsの値を入力レコードのフィールドから取得します。expireとtimeoutの値は秒単位の自然数で指定します。

対象

EXPR
イベントコンテキストを生成する条件式。条件式の評価結果がnullでもfalseでもない場合にイベントコンテキストを生成します。

入力フィールド

dynamic=tでない場合:

フィールドタイプ必須説明
keyオプションで指定したフィールド任意のタイプ必須イベントコンテキストのキー値。nullの場合はイベントコンテキストを生成しません

dynamic=tの場合:

フィールドタイプ必須説明
topicstring必須イベントトピック名。nullまたは文字列でない場合は_errorフィールドにエラーメッセージを割り当てます
key任意のタイプ必須イベントコンテキストのキー値。nullの場合は_errorフィールドにエラーメッセージを割り当てます
expire数値任意有効期限（秒単位）。0以下または数値でない場合は_errorフィールドにエラーメッセージを割り当てます
timeout数値任意タイムアウト（秒単位）。0以下または数値でない場合は_errorフィールドにエラーメッセージを割り当てます
maxrows数値任意最大行数。0未満または数値でない場合は_errorフィールドにエラーメッセージを割り当てます

エラーコード

解析エラー
エラーコードメッセージ説明
23300topicオプションを設定してください。dynamic=tでないのにtopicオプションがない場合
23301keyオプションを設定してください。dynamic=tでないのにkeyオプションがない場合
23302expire値は時間範囲形式で指定する必要があります。s（秒）、m（分）、h（時）、d（日）、mon（月）単位で指定できます。expire値が時間範囲形式でない場合
23303timeout値は時間範囲形式で指定する必要があります。s（秒）、m（分）、h（時）、d（日）、mon（月）単位で指定できます。timeout値が時間範囲形式でない場合
23304maxrows値は0または正の整数を指定する必要があります。maxrows値が0未満または整数でない場合
23305evtctxaddコマンドを実行する条件式を指定してください。条件式が指定されていない場合
ランタイムエラー

N/A

説明

evtctxaddコマンドは入力レコードを走査し、各レコードが条件式と一致した場合に指定したトピックとキーでイベントコンテキストを生成または更新します。イベントコンテキストは複合イベント処理（CEP）のためのメモリストレージに保持されます。

イベントコンテキストには有効期限（expire）とタイムアウト（timeout）を設定できます。有効期限はイベントコンテキストが生成された時点からの絶対的な存続期間であり、条件に一致するデータが追加で入力されても延長されません。一方、タイムアウトは最後に条件に一致するデータを受信した時点から計算されるため、新しいデータが入力されるたびに延長されます。

maxrowsオプションでイベントコンテキストに保存する最大行数を制限できます。保存された行は後でevtctxget()関数で取得できます。

dynamic=tオプションを使用すると、トピック、キー、有効期限、タイムアウト、最大行数を入力レコードのフィールドから動的に取得します。この場合、topic、key、expire、timeout、maxrowsオプションは無視されます。動的モードで必須フィールドが欠落しているか値が有効でない場合は、該当レコードの_errorフィールドにエラーメッセージを割り当てイベントコンテキストを生成しません。

入力レコードはイベントコンテキストの生成の有無に関わらず次のコマンドに渡されます。

使用例

  1. 特定のIPから発生するログイン失敗イベントコンテキストを生成する

    table duration=1h login_logs
| evtctxadd topic=login_fail key=src_ip expire=1h timeout=10m src_ip != null and result == "fail"

    src_ipをキーとしてログイン失敗イベントコンテキストを生成します。有効期限は1時間で、最後の失敗イベント受信後10分が経過するとタイムアウトで削除されます。

  2. 最大保存行数を指定してイベントコンテキストを生成する

    table duration=1h firewall_logs
| evtctxadd topic=port_scan key=src_ip expire=30m maxrows=100 action == "deny"

    ファイアウォールの遮断ログからsrc_ipをキーにイベントコンテキストを生成し、最大100行を保存します。

  3. 動的モードでイベントコンテキストを生成する

    json "[{'topic': 'brute_force', 'key': '192.0.2.1', 'expire': 3600, 'timeout': 600, 'src_ip': '192.0.2.1', 'result': 'fail'}]"
| evtctxadd dynamic=t result == "fail"

    入力レコードのtopic、key、expire、timeoutフィールドの値を使用してイベントコンテキストを動的に生成します。expireとtimeoutの値は秒単位です。