Csysdig View Format Reference
views are the core of csysdig's data processing system. Understanding them allows you to customize and extend csysdig.
Views are Lua scripts that specify both what data csysdig will show on the screen and how it will be presented. This information is expressed as a Lua table which contains general view details like name, type and description, and specific details for each column that the view contains.
This document explains how views work and documents their format. After you're done reading it, you should be able to modify or extend csysdig.
The curious reader might wonder why, since views have a strictly declarative format, we opted for Lua tables as the base for their syntax instead of something more general like json. There are two reasons:
- The sysdig code base already already has support for Lua, so leveraging it came at no additional cost and didn't require the introduction of a second parser.
- More importantly, we don't foresee Views to always be strictly declarative. In the future, we want views to be able to actively generate their own data, by either processing the sysdig/csysdig event stream or by interacting with the system.
At its core, the csysdig data system is very simple. It captures system events (for example system calls) using the sysdig engine, it processes these events to produce fields similar to the ones that you use for filters in vanilla sysdig, and then it puts these fields in tables. There are two types of views: table views and list views.
Think about a table view as a mini SQL table with one primary key. This image shows how a csysdig table view is created:
- The data processing starts from an event, for example an write system call. Arbitrary sysdig filter fields can be extracted from this event. In this example we're extracting two fields, the file name (fd.name), and the write size (evt.buflen).
- The first field is used as a key for a lookup table. Since foo.txt is already present in the table, the evt.buflen value from the event (25) is added to the one in the table entry. This is because we chose SUM as the aggregation for that column, but other aggregations, like MIN, MAX and AVG are available too.
- At regular intervals (usually 2 seconds, but this can be configured using the -d command line switch) the content of the table is rendered on the terminal and the table is cleared so that it's it ready for the next sample.
As the name suggests, table views are perfect to render information that is tabular by its nature: process lists, file lists, network connections, and so on.
Think about a list view as an array. When you throw something at it, it will be appended at the end. This image shows how a list view works:
- The extraction process works exactly like the one of table views.
- However, list views have no keys, so every new row is added at the end of the list. This means that there can be duplicates.
- List views don't have a flush interval. Their content is flushed to the terminal each time an event is received. List views are not periodically cleared. If you want to empty one, you need to do it explicitly by pressing the 'c' key on the keyboard, otherwise it will grow indefinitely.
List views are ideal to render event-based things, like the list of files that a process opens, the commands that a user executes, the connections established on a port, and so on. Since list views don't perform any aggregation, they can easily generate a lot of data, so it's recommended that you always set the filter field for them.
In order to be recognized as a view, a Lua script must include a table called view_info. The table contains both the general details about the view and a sub-table called columns with the details of each of the columns.
This section of the document documents the fields that can be used for both the view and the columns.
id
The View ID. This field must be unique, and is used for internal view identification. It's also used as the argument of the -v csysdig command line flag to manually run the view.
name
The View Name. This will be shown on the top left of the user interface, so it must be short.
description
The view description. This is shown in the view help page, and can have arbitrary length.
tips
An array of strings that contain tips related to using this view. These tips are shown in the view help page, and can have arbitrary length.
view_type
This can be "table" or "list", and indicates if this is going to be a table view or a list view. If "table" is used here, the view must have a key column. If "list" is used here, the view must not have a key column. Failure to comply with these requirements will cause the view to fail loading.
filter
This field accepts a sysdig filter that will be executed by csysdig before feeding events to the view. As a consequence, you get a lot of flexibility in limiting the kind of data that the view processes.
applies_to
This is a list of sysdig fileds that identifies which key types this view can be attached to.
When you click on an element in the csysdig UI, csysdig needs to determine which views can be applied to that element. It does that by scanning the list of views, checking the apply_to list for each of them, and accepting the ones that contain the element key in their apply_to. Said in another way, if you put proc.pid here, this view will be available as a drill down view when the user clicks on a process.
Putting an empty string in this list will make it appear in the root list of views, i.e. the list that appears when csysdig starts, before any drill down is performed.
is_root
Set this field to true if you want this view to be the first one to show up when csysdig starts. Note that, if more than one view has this flag set, csysdig will start with the first one it loads, which you can assume is random.
drilldown_target
Allows to specify the view that will be loaded when the user types enter on this view.
use_defaults
This flag determines what happens when one of the column fields is not present for a received event. If this is set to false, the event will be dropped and no update to the table will happen. If this is set to true, the fields that don't exist will be assumed to be zero, and the event will be inserted in the table.
columns
The list of columns for this view. See the next section.
Actions
The list of hotkey actions for this view. See the Action Fields section below.
name
The column name. This will be printed by csysdig in the column header, so it should be very short.
description
The column description. This is shown in the view help page, so it can have arbitrary length.
is_key
true if this column is a key. Note that only one key is accepted for table views, and none is accepted for list views. Note also that key columns will not appear in the csysdig output. If you need to show a column key, you must define a duplicate that is not a key.
tags
Specifies one or more tags that allow column filtering. For the moment, the only supported tag is containers. This a column with this tag will only be shown when the -pc flag is specified on the command line when starting csysdig.
field The sysdig field extracted for this column. This can be any of the fields listed by 'sysdig -l". This means that you have a lot of options.
colsize
The horizontal size (in characters) that this column will have when rendered on the screen.
aggregation
For numeric fields, this is the aggregation that the engine performs when adding the value to a table view. It can be one of SUM, AVG, MIN and MAX. This field is optional and can be omitted in list views.
is_sorting
If this field is set to true, the view will be sorted by this column.
hotkey
The key associated with this action. Pressing the key in csysdig when this view is loaded will cause the action to start.
command
The command line executed when the key is pressed. The command line can contain any of the views field, with the syntax %field. For example, assuming that the view contains a proc.pid column, you can include its value like this: "kill -9 %proc.pid".
description
A human readable short description of the hotkey action, which will be shown when F7 or F8 are pressed.
wait_finish
'false' if the executed command should return immediately. 'true' if the user should hit enter before returning to csysdig (so that he has time to read the output). This field is optional and the default value is true.
Default csysdig views can be found in the sysdig chisel folder, /usr/share/sysdig/chisels. Alternatively, you can add your own views in ~/.chisels and csysdig will pick them up.
Let's finish this manual with a simple working example: a view that will list all the processes that have opened files in /etc, sorted by the number of files that they opened.
view_info =
{
id = "test_etc_open",
name = "/etc Open Count",
description = "This is a test view that shows how many times each process opens a file in /etc.",
view_type = "table",
filter = "evt.type=open and fd.name contains /etc",
applies_to = {"", "proc.pid"},
drilldown_target = "files",
use_defaults = true,
columns =
{
{
name = "NA",
field = "proc.pid",
is_key = true
},
{
is_sorting = true,
name = "OPEN COUNT",
field = "evt.count",
description = "The number times the process has opened files in /etc.",
colsize = 12,
aggregation = "SUM"
},
{
name = "Command",
description = "The full command line of the process.",
field = "proc.exeline",
colsize = 200
}
},
actions =
{
{
hotkey = "k",
command = "kill %proc.pid",
description = "kill",
wait_finish = false
},
},
}Note how:
- the view has a filter that restricts his input to open events for file descriptor whose name contains /etc.
- applies to is {"", "proc.pid"}. This means that the view will appear in the main view selector and when you drill down in a process.
- drilldown_target is set to "files", a view that will show us the list of files that the selected process is opening in /etc. A nice exploration sequence! ;-)
- the view has three columns, two of which are visible, and is sorted by the OPEN COUNT column.
- the view has an action, which lets you kill the selected process and is triggered by pressing the 'k' key.
Now you just have to save this view in ~/.chisels (remember to give it a .lua extension), and you will be ready to enjoy your exploration!