update: address reviewer suggestions

Co-authored-by: Melissa Kilby <[email protected]>
Signed-off-by: Gianmatteo Palmieri <[email protected]>

content/en/docs/metrics/falco-metrics.md

@@ -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 %}}

content/en/docs/reference/plugins/plugin-api-reference.md

@@ -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;
 ```
 
@@ -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.
@@ -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.