evtctxadd

Creates an event context with the specified topic and key when input data matches a condition expression. If an event context with the same key already exists, its timeout is extended.

Command properties

Syntax

Options

topic=STR

Event topic name. Assign a unique name to distinguish from events of other rules. Ignored when dynamic=t.

key=STR

Name of the field from which to extract the key value that identifies the event context. Ignored when dynamic=t.

expire=INT{s|m|h|d|mon}

Expiration time. The event context is deleted when the specified time elapses from the time the context was created. The expiration time is not extended even if additional input data matching the condition arrives. Ignored when dynamic=t.

• s: seconds
• m: minutes
• h: hours
• d: days
• mon: months

timeout=INT{s|m|h|d|mon}

Timeout. The event context is deleted when the specified time elapses from the last time a matching event was received. The timeout is extended each time new matching data arrives. Ignored when dynamic=t.

• s: seconds
• m: minutes
• h: hours
• d: days
• mon: months

maxrows=INT

Maximum number of rows to store in the event context. Ignored when dynamic=t. (default: 10)

logtick=STR

Name of the external clock host field. When specified, the host name is extracted from that field in the input record, and the event clock advances based on the time in the _time field.

dynamic=BOOL

When set to t, the topic, key, expire, timeout, and maxrows values are taken from fields in the input record. The expire and timeout values must be specified as positive integers in seconds.

Target

EXPR

Condition expression for creating an event context. The event context is created when the result of evaluating the expression is neither null nor false.

Input fields

When dynamic=t is not set:

When dynamic=t is set:

Error codes

Parse errors

Runtime errors

N/A

Description

The evtctxadd command iterates over input records, and when each record matches the condition expression, it creates or updates an event context with the specified topic and key. Event contexts are stored in an in-memory store for complex event processing (CEP).

An event context can have an expiration time (expire) and a timeout (timeout). The expiration time is an absolute lifetime from the moment the context is created; it is not extended even if additional matching data arrives. The timeout, on the other hand, is calculated from the last time matching data was received, so it is extended each time new data arrives.

The maxrows option limits the maximum number of rows stored in the event context. Stored rows can later be retrieved using the evtctxget() function.

When you use the dynamic=t option, the topic, key, expiration time, timeout, and maximum number of rows are taken dynamically from fields in the input record. In this case, the topic, key, expire, timeout, and maxrows options are ignored. In dynamic mode, if a required field is missing or its value is invalid, an error message is assigned to the _error field of that record, and the event context is not created.

Input records are passed to the next command regardless of whether an event context is created.

Examples

1. Create an event context for login failure events from a specific IP

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

   Creates event contexts for login failure events using src_ip as the key. The expiration time is 1 hour, and the context is deleted by timeout 10 minutes after the last failure event is received.

2. Create an event context with a maximum row limit

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

   Creates event contexts from firewall block logs using src_ip as the key, storing up to 100 rows.

3. Create an event context in dynamic mode

   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"
   

   Dynamically creates event contexts using the topic, key, expire, and timeout field values from the input record. The expire and timeout values are in seconds.