Skip to content

Commit

Permalink
update: address reviewer suggestions
Browse files Browse the repository at this point in the history
Co-authored-by: Melissa Kilby <[email protected]>
Signed-off-by: Gianmatteo Palmieri <[email protected]>
  • Loading branch information
mrgian and incertum committed Jun 24, 2024
1 parent de18331 commit 318ab29
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 5 deletions.
2 changes: 2 additions & 0 deletions content/en/docs/metrics/falco-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -1275,6 +1275,8 @@ Please note that this doesn't provide default metrics about the plugin itself, a

Currently, none of the officially maintained plugins provides any metric, but this will change in the future.

Lastly, please note that as of Falco 0.38.1, it is not possible to fully use the remaining metrics feature when running plugins without the syscalls source. This is due to some regressions that prevent us from serving a small subset of metrics in this scenario. Near-term improvements in this regard are tracked in the following issue. Please also keep in mind that many of the metrics categories are specific to the syscalls source, such as `libbpf_stats_enabled`, `kernel_event_counters_enabled`, or `state_counters_enabled`.

## Breaking Changes

{{% pageinfo color=info %}}
Expand Down
41 changes: 36 additions & 5 deletions content/en/docs/reference/plugins/plugin-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -233,10 +233,10 @@ Each element of the array is a `ss_plugin_metric` which is [defined](https://git
```CPP
typedef struct ss_plugin_metric
{
const char* name; //Opaque string representing the metric name
ss_plugin_metric_type type; // Metric type
ss_plugin_metric_value value; // Metric numeric value
ss_plugin_metric_value_type value_type; // Metric value data type
const char* name; //Opaque string representing the metric name.
ss_plugin_metric_type type; // Metric type, indicates whether the metric value is monotonic or non-monotonic.
ss_plugin_metric_value value; // Metric numeric value.
ss_plugin_metric_value_type value_type; // Metric value data type, e.g. `uint64_t`.
} ss_plugin_metric;
```

Expand Down Expand Up @@ -787,7 +787,7 @@ typedef struct

Obtaining table accessors is a bit different for subtables.

Table accessors can be only obtained at initialization time, however tables may be empty at this time, which means subtables may be not existing yet.
Table accessors can be only obtained at initialization time, however tables may be empty at this time, which means subtables may not yet exist.
The solution to this problem is to create a table entry just to get its subtables.

Please note that this newly created entry is temporary and it should be used only at initialization time to obtain subtable accessors.
Expand Down Expand Up @@ -895,6 +895,37 @@ typedef struct
} ss_plugin_table_writer_vtable;
```

### Accessing subtables

Subtables handles can be obtained just like any other field, by reading the `table` type field of an entry.

After obtaining subtables handles and [fields accessors](#obtaining-subtables-accessors), accessing subtables is the same as accessing regular tables.

The following example shows how to access fields from the `file_descriptors` subtable from one of the entries of the `threads` table:

```CPP
ss_plugin_rc plugin_parse_event(ss_plugin_t *s, const ss_plugin_event_input *ev, const ss_plugin_event_parse_input* in)
{
plugin_state *ps = (plugin_state *) s;
ss_plugin_state_data tmp;

// get an entry from the thread table
tmp.s64 = ev->evt->tid;
ss_plugin_table_entry_t* thread_entry = in->table_reader_ext->get_table_entry(ps->thread_table, &tmp);

// read the file_descriptors field from the entry
in->table_reader_ext->read_entry_field(ps->thread_table, thread_entry, ps->table_field_fdtable, &tmp);
ss_plugin_table_t* fdtable = tmp.table;

// get an entry from the file descriptors table of the previously read thread
tmp.s64 = 0;
ss_plugin_table_entry_t* fd_entry = in->table_reader_ext->get_table_entry(fdtable, &tmp);

// read a field from the entry in the file desciptors table
in->table_reader_ext->read_entry_field(fdtable, fd_entry, ps->table_field_fdtable_name, &tmp);
}
```
### Registering State Tables
On top of accessing tables owned by the framework or other plugins, each plugin can also make part (or all) of its state available to other actors in the framework in the form of state tables. In this case, the plugin is responsible of providing all the necessary vtables and their respective functions, just like the Falcosecurity libraries do for the tables owned by them (e.g. the `threads` table). Plugins have total freedom towards how the table is actually implemented, as long as they respect the API functions in the vtables and they own all the memory related to the table and its entries. Plugins also have the freedom of not supporting some of the functions of the vtables, however they are not allowed to pass NULL-pointing function references. The struct by which plugins register their state table and the related vtable functions is reported below.
Expand Down

0 comments on commit 318ab29

Please sign in to comment.