A lua event filter and its methods. More...

#include "event.h"
#include "event_generator.h"

Typedefs
typedef struct actf_lua_filter	actf_lua_filter
	A lua filter, implements an actf_event_generator.

Functions
actf_lua_filter *	actf_lua_filter_init (struct actf_event_generator gen, size_t evs_cap)
	Initialize a lua filter struct.
int	actf_lua_filter_lua_init (actf_lua_filter f, const char filter_path, int filter_argc, char *filter_argv[])
	Initialize the lua part of the filter and call actf.init.
int	actf_lua_filter_filter (actf_lua_filter f, actf_event *evs, size_t evs_len)
int	actf_lua_filter_seek_ns_from_origin (actf_lua_filter *f, int64_t tstamp)
const char *	actf_lua_filter_last_error (actf_lua_filter *f)
int	actf_lua_filter_lua_fini (actf_lua_filter *f)
	Finalize a filter, calling actf.fini.
void	actf_lua_filter_free (actf_lua_filter *f)
	Free a filter.
struct actf_event_generator	actf_lua_filter_to_generator (actf_lua_filter *f)
	Create an event generator based on a filter.

Detailed Description

A lua event filter and its methods.

The lua filter reads in a lua file and filters event based on it. Three separate functions are supported in the lua file, actf.init, actf.filter and actf.fini. actf.filter is mandatory.

The lua filter is designed to be used for quick ad-hoc filtering or processing, therefore the full actf API is not exposed to it. The lua bindings are focused around accessing an event's fields and values.

Lua Filter Callbacks

actf.init(...)

actf.init is is called by actf_lua_filter_lua_init(), takes a variable number of string arguments as input and returns a status code, zero or nil means success.

actf.filter(ev)

actf.filter is called for every event entering the filter. The given event and its components (packet, fields) are only valid during this call and should not be kept around. Values, such as numbers and strings, are copied into lua and can be kept for later referencing. It should return 0 to keep the event, 1 to filter the event and <0 to error out; nil is classified as 1.

actf.fini()

actf.fini is called as a finalization step by actf_lua_filter_lua_fini(). It should return a status code, zero or nil means success.

Example filter

The following filter prints the arguments it was given during initialization and performs the simple task of counting the number of events grouped by their names which it then prints at the end.

function setDefault(t, d)
   local mt = {__index = function () return d end}
   setmetatable(t, mt)
end
 
function actf.init(...)
   stats = {}
   setDefault(stats, 0)
   print("init with "..tostring(select("#", ...)).." args:")
   for i,v in ipairs(table.pack(...)) do
      print(i, v)
   end
end
 
function actf.filter(ev)
   local name = ev:name() or "UNNAMED EVENT"
   stats[name] = stats[name] + 1
   return 1
end
 
function actf.fini()
   for name, cnt in pairs(stats) do
      print(name, cnt)
   end
end

Lua Types

These are the actf types and their methods that are exposed to lua.

Field Representations

actf fields apart from the compound types are represented as regular lua types. This is what will be returned when you access a field using get(). The signed integer (SINT), unsigned integer (UINT) and bit map types return their integer value followed by all their associated mappings or flags.

actf_fld_type	lua type
NIL	nil
BOOL	boolean
SINT	integer, [string...]
UINT	integer, [string...]
BIT_MAP	integer, [string...]
REAL	number
STR	string
BLOB	string
STRUCT	compound field
ARR	compound field

Raw Field Represenations

When accessing fields using rawget(), you will receive a field or a compound field rather than a resolved value. This allows you to access more properties of the field such as attributes.

actf_fld_type	lua type
NIL	field
BOOL	field
SINT	field
UINT	field
BIT_MAP	field
REAL	field
STR	field
BLOB	field
STRUCT	compound field
ARR	compound field

Field

A non-compound field is represented with this lua type. This is what can be returned from rawget() methods.

name	description	return type
value	resolve the field into a lua value	the field type's lua type
attributes	get the field's attributes	field or nil
extensions	get the field's extensions	field or nil
__tostring	get the field's string representation	string

Compound Field

A compound field, struct or array, are represented with a special lua type. An array's elements can be accessed using get() with an integer as the argument (1-based indexing). A struct's members can be accessed using get() with either a string or an integer as the argument. A string is matched against the members' names and an integer is interpreted as the Nth member (1-based indexing). The following methods are defined for a compound type:

name	description	arguments	return type
get	get a field of the compound field	string or integer	field or nil
rawget	get a non-resolved field of the compound field	string or integer	field or nil
attributes	get the field's attributes		field or nil
extensions	get the field's extensions		field or nil
__len	get the number of elements or members in the field		integer
__tostring	get the field's string representation		string

Event Methods

An event has the following methods defined:

name	description	arguments	return type
namespace	get the event's namespace		string or nil
name	get the event's name		string or nil
uid	get the event's uid		string or nil
get	get a field in the event or packet	string	field or nil
rawget	get a non-resolved field in the event or packet	string	field or nil
header	get the event's header		field or nil
context	get the event's context		field or nil
specific_context	get the event's specific context		field or nil
payload	get the event's payload		field or nil
packet	get the event's packet		packet
timestamp	get the event's raw timestamp		integer
timestamp_ns	get the event's timestamp in nanoseconds from origin		integer
attributes	get the event's attributes		field or nil
extensions	get the event's extensions		field or nil
__tostring	get the event's string representation		string

Packet Methods

A packet has the following methods defined:

name	description	arguments	return type
get	get a field of the packet	string	field or nil
rawget	get a non-resolved field of the packet	string	field or nil
header	get the packet's header		field or nil
context	get the packet's context		field or nil
sequence_number	get the packet's sequence number		integer or nil
begin_timestamp	get the packet's raw begin timestamp		integer
begin_timestamp_ns	get the packet's begin timestamp in nanoseconds from origin		integer
end_timestamp	get the packet's raw end timestamp		integer or nil
end_timestamp_ns	get the packet's end timestamp in nanoseconds from origin		integer or nil
discard_snapshot	get the packet's discarded event snapshot		integer or nil

Typedef Documentation

◆ actf_lua_filter

typedef struct actf_lua_filter actf_lua_filter

A lua filter, implements an actf_event_generator.

It should be setup and used in the following order:

actf_lua_filter_init
actf_lua_filter_lua_init
<event processing usage>
actf_lua_filter_lua_fini
actf_lua_filter_free

Function Documentation

◆ actf_lua_filter_init()

actf_lua_filter * actf_lua_filter_init	(	struct actf_event_generator	gen,
		size_t	evs_cap )

Initialize a lua filter struct.

The lua state and filter should be loaded subsequently in actf_lua_filter_lua_init(). The initialization is a two-step process to allow us to return detailed error messages using actf_lua_filter_last_error().

Parameters

gen	the generator to filter
evs_cap	the max event array capacity. If zero, ACTF_DEFAULT_EVS_CAP will be used. This should in general be set to the same capacity as the provided generator.

Returns: a filter or NULL with errno set. A returned filter should be freed with actf_filter_free().

◆ actf_lua_filter_lua_init()

int actf_lua_filter_lua_init	(	actf_lua_filter *	f,
		const char *	filter_path,
		int	filter_argc,
		char *	filter_argv[] )

Initialize the lua part of the filter and call actf.init.

Parameters

f	the lua filter struct
filter_path	the path of the lua filter
filter_argc	the number of args given to the filter
filter_argv	the args given to the filter

Returns: ACTF_OK on success or an error code. On error, see actf_last_error().

◆ actf_lua_filter_filter()

int actf_lua_filter_filter	(	actf_lua_filter *	f,
		actf_event ***	evs,
		size_t *	evs_len )

See also: actf_event_generate. Will call actf.filter to filter each event.

◆ actf_lua_filter_seek_ns_from_origin()

int actf_lua_filter_seek_ns_from_origin	(	actf_lua_filter *	f,
		int64_t	tstamp )

See also: actf_seek_ns_from_origin

◆ actf_lua_filter_last_error()

const char * actf_lua_filter_last_error ( actf_lua_filter * f )

See also: actf_last_error

◆ actf_lua_filter_free()

void actf_lua_filter_free ( actf_lua_filter * f )

Free a filter.

Parameters

f	the filter

◆ actf_lua_filter_to_generator()

struct actf_event_generator actf_lua_filter_to_generator ( actf_lua_filter * f )

Create an event generator based on a filter.

The filter is owned by the caller and must be kept alive as long as the event generator is in use.

Parameters

f	the filter

Returns: an event generator

Typedefs

Functions

Detailed Description

Lua Filter Callbacks

actf.init(...)

actf.filter(ev)

actf.fini()

Example filter

Lua Types

Field Representations

Raw Field Represenations

Field

Compound Field

Event Methods

Packet Methods

Typedef Documentation

◆ actf_lua_filter

Function Documentation

◆ actf_lua_filter_init()

◆ actf_lua_filter_lua_init()

◆ actf_lua_filter_filter()

◆ actf_lua_filter_seek_ns_from_origin()

◆ actf_lua_filter_last_error()

◆ actf_lua_filter_free()

◆ actf_lua_filter_to_generator()