Sysdig Chisel API Reference Manual - draios/sysdig GitHub Wiki

sysdig chisels are Lua scripts that can be invoked from the sysdig command line, hook into the sysdig engine, and can be used to extend sysdig with advanced funcionality.

Chisels talk with sysdig using three separate interfaces:

  • Callbacks a set of callbacks that get called when something interesting happens, e.g. when an event is received
  • sysdig library, with functions to interact with the main program
  • evt library, used to extract information from a captured event

This page documents each of these interfaces.

Mandatory Globals

In order to be recognized as a chisel, a Lua script must export the following global variables:

  • description: a string containing the chisel verbose description
  • short_description: a string that explains what the chisel does in a few words, and can be used in a list
  • category: the chisel category, e.g. IO, net, security, etc.
  • args: a table describing each of the chisel arguments, in the following format:
description = "a string containing the chisel verbose description"
short_description = "a string that explains what the chisel does in a few words"
category = "the chisel category"

-- Chisel argument list
args = 
{
	{
		name = "name1", 
		description = "description1", 
		argtype = "ipv4"
		optional = false
	},
	{
		name = "name2", 
		description = "description2", 
		argtype = "string"
		optional = true
	},
}

Notes:

  • If optional is set to false, sysdig expects the argument to be specified on the command line after the chisel name, and will fail if the argument is not there.
  • Each argument in args generates a call to the on_set_arg() callback.
  • args can be empty if the chisel doesn't require any argument.
  • If more than 1 argument is provided the argument list for chisels must be encapsulated with "". E.g. sysdig -c chisel_name "arg1 arg2 arg3"

Callbacks

Callbacks are the way sysdig uses to notify a chisel that something has happened. Most callbacks don't need to be registered. Just include the function in the chisel and, if present, the engine will call it. The only exception is on_interval(), which needs to be registered with sysdig.set_interval_s() or sysdig.set_interval_ns(). Callbacks are optional. If you don't need one of them, just don't include it.

on_set_arg(name, val)

This callback is called by the engine for every argument contained in the args global table. name is the name of the argument to set, while val is the value that the user specified on the sysdig command line.

Returning false means that the parameter is not valid and will cause sysdig to quit.

on_init()

Called by sysdig after on_set_arg() has been called for every chisel argument, but before the capture is configured. Usually, this is where the chisel initialization happens.

Returning false means that the chisel initialization failed and will cause sysdig to quit.

on_capture_start()

Called by sysdig after the capture is configured, after on_set_arg() has been called for every chisel argument, but before any packet has been captured. It can be used for final chisel initializations that require to query the capture state.

Returning false means that the chisel initialization failed and will cause sysdig to quit.

on_event()

Invoked every time one of the captured events passes the filter specified with set_filter(), or for each event if set_filter() has not been called. This is the function that usually contains the core chisel logic, and where you want to make sure things are efficient. From this callback you have access to the evt library to extract information from the currently processed event.

If you specified a formatter, returning false in on_event() will make the formatter ignore the event.

on_capture_end(ts_s, ts_ns, delta)

Called by the engine at the end of the capture, i.e.

  • When CTRL+C is pressed for live captures.
  • After the last event has been read from offline captures.

The function receives the following arguments:

  • ts_s, ts_ns: the second and nanosecond parts of the timestamp of the last event in the capture
  • delta: the time between the first and last packet in the capture, in nanoseconds

on_interval(ts_s, ts_ns, delta)

Periodic timeout callback. Can be used to do things like reporting information once a second. Use chisel.set_interval_s() or chisel.set_interval_ns() to configure it.
The function receives the following arguments:

  • ts_s, ts_ns: the second and nanosecond parts of the time when this function is called
  • delta: the delta time between the call and the previous call to on_interval()

sysdig library

The functions in this library can be used to get or set global sysdig configuration, like the snaplen or the program capture filter.

sysdig.end_capture()

Available from version 0.1.88

This call causes sysdig to stop receving events and makes it initiate the end of capture cleanup.

sysdig.get_machine_info()

Return a table with information about the machine generating the events. The returned table has this fields:

  • num_cpus: the number of CPU cores on the machine
  • memory_size_bytes: the machine RAM size
  • max_pid: the maximum pid allowed on the machine
  • hostname: the machine hostname

Note: this call works with file captures as well, because the machine info is stored in the trace files. In that case, the returned machine info is the one of the machine where the capture happened.

sysdig.get_filter()

Available from version 0.1.87

Return a string containing the filter that was passed to sysdig on the command line.

sysdig.get_evtsource_name()

Available from version 0.1.87

Return a string containing the name of the event source, either the trace file name (if the events are coming from a trace file), or "" (if this is a live capture).

sysdig.get_output_format()

Return a string with the output format that the user specified on the command line. The return value can be "normal" or "json".

sysdig.is_print_container_data()

Available from version 0.1.98

A boolean value indicating if the -pc or -pcontainer sysdig flag has been provided. Specifically this is used to switch the chisel from not printing or printing container information. If true then the -pc or -pcontainer flag was used and false otherwise.

sysdig.get_container_table(filter)

Available from version 0.1.98

Return the sysdig container table.

A filter can be optionally passed as an input parameter to restrict the returned elements. The syntax of the filter is the one used for regular sysdig filters, but only the fd, proc, user and group filter families can be used.

The following values are returned:

  • id: the container id. I.e. the unique identifier associated with this container.
  • name: the container name. I.e. the name provided by the creator.
  • image: the container image text. E.g. Ubuntu, mysql, haproxy, & etc
  • type: the container type. Supported types: (docker, lxc, & libvirt_lxc)
  • Note: (container.id == host) and/or (container.name == host) is the host and not any specific container.

sysdig.get_thread_table(filter)

Available from version 0.1.88

Return the sysdig process table.

A filter can be optionally passed as an input parameter to restrict the returned elements. The syntax of the filter is the one used for regular sysdig filters, but only the fd, proc, user and group filter families can be used.

The return value is a table with the thread PID as key and a table with the following fields as value:

  • tid: the thread id.
  • pid: the process id. Same as tid for single thread processes.
  • ptid: the PID of the process that created this one.
  • comm: the command name (e.g. top)
  • exe: the command full executable name (e.g. /bin/top)
  • args: an array of strings containing the process arguments
  • fdlimit: the maximum number of FDs that this process can open.
  • uid: the ID of the user that started this process.
  • username: the name of the user that started this process.
  • gid: the user group ID of the user that started this process.
  • vmsize_kb: the process' virtual memory size.
  • vmrss_kb: the process' resident memory size.
  • vmswap_kb: the process' swap memory size.
  • pfmajor: the number of major page faults that this thread generated since it was started.
  • pfminor: the number of minor page faults that this thread generated since it was started.
  • fdtable: the file descriptor table for this process. This field is a table with the FD number as key and a table with the following fields as value:
  • name: the FD name. The format of this field depends on the FD type and can be empty. For example, this field contains the full name for files, and the tuple for sockets.
  • type: the FD type. Can have one of the following values: file, directory, ipv4, ipv6, unix, pipe, event, signalfd, eventpoll, inotify, timerfd.
  • sip: if the FD is a socket, the server IP address.
  • sport: if the FD is a socket, the server IP port.
  • cip: if the FD is a socket, the client IP address.
  • cport: if the FD is a socket, the client port.
  • is_server: true if the FD is a socket and the server side is on this machine.
  • l4proto: if the FD is a socket, the transport protocol. Can have one of these values: tcp, udp, icmp, raw.

sysdig.is_tty()

Available from version 0.1.87

Return true if the sysdig is run in an interactive terminal that has ANSI capabilities. Can be used by a chisel to determine if it's possible to use color on the screen.

sysdig.islive()

Return true if the current capture is live, i.e. if the events are coming from a the system and not from a trace file.

sysdig.run_sysdig(args)

Available from version 0.1.87

Exits from this sysdig execution and starts another one, with the arguments given in the args string. It can be used by a chisel to run another one on a different capture, or to start sysdig again to perform a different task (for example saving some events to file).

sysdig.set_fatfile_dump_mode(mode)

Available from version 0.1.87

Enable/disable fatfile mode. The mode argument is a boolean value. 'true' enables fatfile mode, 'false' disables it. Refer to the the -F flag in the sysdig manual for details about fatfile mode.

sysdig.set_filter(filter)

Configure the sysdig capture engine to apply the given filter before parsing the captured events. This has the same result as setting the filter from the sysdig command line, and will override the command line filter if one is specified.

sysdig.set_snaplen(snaplen)

Configure the number of bytes that are captured from buffers of I/O system calls like read(), write(), sendto(), recvfrom(), etc.

chisel library

The functions in this library are mostly related to setting up the chisel environment and are usually called at initialization time, i.e. inside on_init().

chisel.exec(chiselname, arg1, arg2, ...)

This function can be used to stop the execution of the calling chisel and, instead, run a different chisel. The function arguments are the chisel name, followed by the arguments to pass to the new chisel.

chisel.request_field(fld_name)

This function is used to configure the sysdig engine to extract a filter field when an event is captured. fld_name is the name of the sysdig filter field to extract (see the sysdig tutorial or type sysdig -l for a list of available fields). The function returns a field handle that can be fed to evt.field() to get the field value from the on_event() callback.

chisel.set_filter(filter)

Configure the sysdig engine to apply the given filter before handing the events to this chisel's on_event() callback.

Notes

  • The filter set with set_filter() is private for this chisel and won't influence other chisels that are run from the same command line.
  • You can set only one filter per chisel. Calling set_filter() twice will cause the first filter to be overridden.
  • It's very important to be as aggressive as possible with filters. The sysdig engine is heavily optimized, so eliminating as many events as possible before reaching the chisel's on_event() will make the chisel much more efficient.

chisel.set_event_formatter(format)

Configure an event formatter. format is a string containing a list of fields to print, with the same syntax that you would use with the -p sysdig command line switch (refer to the sysdig manual for more information).

By default, chisels have no event formatter, and that gives them the freedom to print whatever they want using Lua's print() function. Setting a formatter, on the other hand, lets you delegate event formatting to sysdig, leveraging sysdig's filter fields system. Use the string "default" or an empty string, "", to let sysdig apply its default format to the chisel output. Note that only events for which on_event() returns true are going to be printed. Also note, chisel output will not be overridden with the -p flag.

chisel.set_interval_s(interval)

Set a periodic callback for this chisel. If you use this function, the chisel needs to include a function called on_interval(), which the engine will call every interval seconds. This can be used to perform periodic tasks, like printing information to the screen once a second.

chisel.set_interval_ns(interval)

Like set_interval_s(), but allows more granular timeouts.

evt library

The functions in this library are related to the event that is currently processed and therefore can only be called from the on_event() callback.

evt.get_cpuid()

Return number of the CPU where this event was captured.

evt.field(fld)

Extract a field's value from an event. fld is a field handle obtained from a previous call to request_field(). The function returns the field value, which can be a number or a string depending on the field. Use sysdig -lv to find out the type of each exported field.

Notes

  • If the requested field is not exported by an event (e.g. non I/O events don't export the fd.name field), the return value of field() will be nil.
  • One important field you need to be aware of is evt.rawarg. This field can be used to extract arbitrary system call arguments, e.g. evt.rawarg.res, and its type depends on the field you're asking. Use sysdig -L to find out the type of event arguments.

evt.get_num()

Return the incremental event number.

evt.get_ts()

Returns two integers representing the second and nanosecond parts of the raw event timestamp respectively.

evt.get_type()

Return the event type as a number. This function can be used for efficient event filtering. For the list of event type numbers, please refer to the ppm_event_type enumeration in driver/ppm_event_events_public.h.