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の場合:

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

エラーコード

解析エラー

エラーコード	メッセージ	説明
23300	topic is required.	`dynamic=t`でないのに`topic`オプションがない場合
23301	key is required.	`dynamic=t`でないのに`key`オプションがない場合
23302	expire should be timespan format. You should use s(second), m(minute), h(hour), d(day), mon(month) time unit	`expire`値が時間範囲形式でない場合
23303	timeout should be timespan format. You should use s(second), m(minute), h(hour), d(day), mon(month) time unit	`timeout`値が時間範囲形式でない場合
23304	maxrows should be zero or positive integer.	`maxrows`値が0未満または整数でない場合
23305	specify conditional expression for evtctxadd	条件式が指定されていない場合

ランタイムエラー

N/A

説明

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

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

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

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

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

使用例

特定の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分が経過するとタイムアウトで削除されます。
最大保存行数を指定してイベントコンテキストを生成する
```
table duration=1h firewall_logs
| evtctxadd topic=port_scan key=src_ip expire=30m maxrows=100 action == "deny"
```
ファイアウォールの遮断ログからsrc_ipをキーにイベントコンテキストを生成し、最大100行を保存します。
動的モードでイベントコンテキストを生成する
```
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の値は秒単位です。