Core procedures

The following procedures are exported by core.

add_stat(string statname, integer value);: Add value to the statistical counter using the current time.

add_stat(string statname, integer value, datetime time);: Add value to the statistical counter using the time specified in the argument named time.

add_to_route(string routename);: Copy the currently processed event data to the route specified. This procedure makes a copy of the data. The original will be processed normally. Note that flow control is explicitly disabled when moving data with add_to_route() and the data will not be added if the queue of the target module(s) is full.

array_append(array dst_array, array src_array, integer src_index, integer src_num_elements);: This procedure copies elements from src_array to the end of dst_array. The src_index specifies the first src_array element index and src_num_elements specifies the number of elements to copy. The size of dst_array will increase by src_num_elements at most. dst_array and src_array must both be array types. The operation is not executed if src_index exceeds the src_array size or src_num_elements is 0.

array_push(array array_value, varargs value);: Pushing the value(s) into the array_value after the highest index value. The size of the array_value will increase by the number of value arguments. If array_value is not an array type then no operation(s) will be carried out.

array_trim(array array_value);: Removing the undef values from the end of the array_value container. The size of the array will decrease if such element(s) was(were) found at the end of the container. If array_value is not an array type then no operation(s) will be carried out.

create_stat(string statname, string type);: Create a module statistical counter with the specified name using the current time. The statistical counter will be created with an infinite lifetime. The type argument must be one of the following to select the required algorithm for calculating the value of the statistical counter: COUNT, COUNTMIN, COUNTMAX, AVG, AVGMIN, AVGMAX, RATE, RATEMIN, RATEMAX, GRAD, GRADMIN, or GRADMAX (see [statistical-counters]).

The interval parameter is optional for COUNT type statistical counters. It is mandatory for all other types.

This procedure will do nothing if a counter with the specified name already exists.

create_stat(string statname, string type, integer interval);: Create a module statistical counter with the specified name to be calculated over interval seconds and using the current time. The statistical counter will be created with an infinite lifetime.

create_stat(string statname, string type, integer interval, datetime time);: Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will be created with an infinite lifetime.

create_stat(string statname, string type, integer interval, datetime time, integer lifetime);: Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will expire after lifetime seconds.

create_stat(string statname, string type, integer interval, datetime time, datetime expiry);: Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will expire at expiry.

create_var(string varname);: Create a module variable with the specified name. The variable will be created with an infinite lifetime.

create_var(string varname, integer lifetime);: Create a module variable with the specified name and the lifetime given in seconds. When the lifetime expires, the variable will be deleted automatically and get_var(name) will return undef.

create_var(string varname, datetime expiry);: Create a module variable with the specified name. The expiry specifies when the variable should be deleted automatically.

debug(unknown arg, varargs args);: Print the argument(s) at DEBUG log level. Same as log_debug().

delete(unknown arg);: Delete a field or a module variable from the event. For example, delete($field) or delete(variable)`. Note that `$field = undef` or `variable = undef is not the same, though after both operations the field or the module variable will be undefined. If the argument is an expression which is not purely a field ($field) or a module variable ($$variable) then the expression will be evaluated and that value will be treated as a name of the field to be deleted. If the expression yields a non-string type value then an error message will be issued.
delete(string arg);: Delete the field from the event. For example, delete("field").

delete_all();: Delete all of the fields from the event except raw_event field.

delete_stat(string statname);: Delete a module statistical counter with the specified name. This procedure will do nothing if a counter with the specified name does not exist (e.g. was already deleted).

delete_var(string varname);: Delete the module variable with the specified name if it exists.

drop();: Drop the event record that is currently being processed. Any further action on the event record will result in a "missing record" error.

hash_remove(hash hash_value, varargs key);: Removing the keys(s) from the hash_value. The size of the hash_value will increase by the number of key arguments. To perform this operation, the key argument(s) must be of string type. If hash_value is not a hash type then no operation(s) will be carried out.

log_debug(unknown arg, varargs args);: Print the argument(s) at DEBUG log level. Same as debug(). Messages longer than specified at LogSizeLimit will be truncated.

log_error(unknown arg, varargs args);: Print the argument(s) at ERROR log level. Messages longer than specified at LogSizeLimit will be truncated.

log_info(unknown arg, varargs args);: Print the argument(s) at INFO log level. Messages longer than specified at LogSizeLimit will be truncated.

log_warning(unknown arg, varargs args);: Print the argument(s) at WARNING log level. Messages longer than specified at LogSizeLimit will be truncated.

module_restart();: Issue module_stop and then a module_start events for the calling module. Cross-module calls are supported: other_module→module_restart().

module_start();: Issue a module_start event for the calling module. Cross-module calls are supported: other_module→module_start().

module_stop();: Issue a module_stop event for the calling module. Cross-module calls are supported: other_module→module_stop().

rename_field(unknown old, unknown new);: Rename a field. For example, rename_field($old, $new).

rename_field(string old, string new);: Rename a field. For example, rename_field("old", "new").

reroute(string routename);: Move the currently processed event data to the route specified. The event data will enter the route as if it was received by an input module there. Note that flow control is explicitly disabled when moving data with reroute() and the data will be dropped if the queue of the target module(s) is full.

set_var(string varname, unknown value);: Set the value of a module variable. If the variable does not exist, it will be created with an infinite lifetime.

sleep(integer interval);: Sleep the specified number of microseconds. This procedure is provided for testing purposes primarily. It can be used as a poor man’s rate limiting tool, though this use is not recommended.