NoDrop Chisel API Reference Manual

This page documents the Lua API currently supported by NoDrop Chisels.

NoDrop Chisels are written in Lua and execute inside the NoDrop monitor. A Chisel processes captured events through callback functions and accesses event data through field handles.

Callback Functions

NoDrop currently supports the following callback functions.

on_init()

Called once when the Chisel is initialized.

This callback is typically used to:

• request field handles
• initialize global state
• open files or prepare other resources

Return value:

• true: initialization succeeds and event processing continues

on_event()

Called once for each captured event delivered to the Chisel.

This callback is used to:

• read event fields
• filter events
• save events
• send events to external systems
• maintain user-defined state

Return value:

• true: continue processing subsequent events

Library API

The following Lua APIs are currently provided by NoDrop.

chisel.request_field(name)

Requests a field and returns a handle that can later be used with evt.field(handle).

Parameters:

• name: field name as a string

Return value:

• a field handle

Notes:

• field handles are typically requested during on_init()
• the returned handle is used to access the value of that field for the current event

evt.field(handle)

Returns the value of the specified field for the current event.

Parameters:

• handle: a field handle returned by chisel.request_field()

Return value:

• the field value for the current event

Notes:

• the returned value depends on the field type
• if the field is not available for the current event, the result may be empty or undefined depending on the event and field combination
• for evt.arg.<name>, the current event must actually contain that argument

evt.save()

Saves the current event in human-readable form to a .log file.

Notes:

• the output is text, not binary
• log files use the same naming convention as recorded event buffers, the filename format is based on thread ID and timestamp

evt.send(ip, port)

Sends the current event in human-readable form through UDP.

Parameters:

• ip: destination IP address
• port: destination UDP port

Supported Fields

NoDrop currently supports the following event fields.

• evt.time

Event timestamp.

Returns the time associated with the current event.

• evt.type

Event type.

Usually corresponds to the event or system call name, such as write, read, open, and so on.

• evt.tid

Thread ID of the current event.

Returns the thread identifier associated with the event.

• evt.arg.<name>

Event argument by name.

This field accesses a specific argument of the current event.

Format:

evt.arg.

Notes:

• this field is only valid if the current event actually has the specified argument
• users must ensure that the argument exists for the event being processed
• different event types support different argument names

For example, accessing evt.arg.fd is only valid for events that contain an fd argument.