update: plugin API reference to version 3.6.0

[mrgian]

What type of PR is this?

Uncomment one (or more) /kind <> lines:

/kind bug

/kind cleanup

/kind design

/kind user-interface

/kind content

/kind event

Any specific area of the project related to this PR?

Uncomment one (or more) /area <> lines:

/area blog

/area documentation

/area community

What this PR does / why we need it:
Updates the plugin API reference to version 3.6.0.
Updates docs about enabling plugin metrics in Falco.

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

Please note that this documents features available in Falco 0.38.1, so it should be merged after the Falco release.

[poiana]

Welcome @mrgian! It looks like this is your first PR to falcosecurity/falco-website 🎉

[mrgian]

cc @FedeDP @incertum @jasondellaluce

[incertum]

Suggested change

	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 be not yet exist.

[incertum]

Could you provide clear examples how to use the new API instead of just providing the source code snippets?

For example how to access the fd table fields and the cmdline args and how is it different from accessing the currently available fields (see below)?

Header:
falcosecurity::table_field m_comm;

CPP:
init(falcosecurity::init_input& in)
{
    using st = falcosecurity::state_value_type;
    auto& t = in.tables();
    m_thread_table = t.get_table(THREAD_TABLE_NAME, st::SS_PLUGIN_ST_INT64);
    m_comm = m_thread_table.get_field(t.fields(), "comm", st::SS_PLUGIN_ST_STRING);
...

std::string tstr;
m_comm.read_value(tr, thread_entry, tstr);

[mrgian]

There is already an example that shows how to obtain subtable accessors.
Once you obtained accessors and subtables handles, accessing subtables fields works just like any other regular table.
But I agree on making this more clear by providing another example 👍🏻

[incertum]

It may seem intuitive to the folks who developed it. For end users who seek to develop a plugin the docs are not sufficient IMO. Instead of source code snippets from libs, what would be better would be clear examples on how to use the API similar to the snippet above.

[leogr]

I agree with @incertum .

Just a question: do we want to address this point in this PR? Or do we want to unblock this PR and enhance its content in a follow-up PR? 🤔

[incertum]

Hm the links seem to show libs snippet again? And does not appear to be an example of how to use it in a real plugin developed with the plugin SDK in the plugins repo.

Given the below example that shows how I read the comm value how do I read m_args, and m_fd_name values?

Header:
falcosecurity::table_field m_comm;

CPP:
init(falcosecurity::init_input& in)
{
    using st = falcosecurity::state_value_type;
    auto& t = in.tables();
    m_thread_table = t.get_table(THREAD_TABLE_NAME, st::SS_PLUGIN_ST_INT64);
    m_comm = m_thread_table.get_field(t.fields(), "comm", st::SS_PLUGIN_ST_STRING);
...

std::string tstr;
m_comm.read_value(tr, thread_entry, tstr);

[mrgian]

@incertum
🤔 I think you are confusing plugin examples written using the plugin API, with libs snippets.
The purpose of the Falco Plugins API Reference page is to document symbols/types of the plugin API which is a plain-C interface.
For this reason, the example I provided shows how to use the plugin API directly without using the C++/Go plugin SDK.

You mentioned accessing the fd_name field. The example I provided shows exactly how to do that: here it shows how to get the field accessor to that field, and here it shows how to use that accessor to obtain the actual fd_name value from one of the subtables.

Again, this example shows how to use the the plugin API and not the plugin SDK.
Documenting the plugin SDK is out of the scope of this website page IMHO.
Also support for subtables in the C++ plugin SDK has not been merged yet (falcosecurity/plugin-sdk-cpp#38)

From what I know, the C++ SDK is still an experimental project, it can be subject to breaking changes and it has not been released. For this reason it has no documentation yet, however it will provide examples.

[incertum]

Hey I am more interested in how to actually use it in a plugin, I added bunch of comments to my open PR falcosecurity/plugins#419 (comment). Appreciate clear examples once the SDK is updated.

[mrgian]

I'll provide some examples when the C++ SDK is ready :)
But I think it should be addressed in another PR, since the goal of this one is updating the plugin API reference.

[leogr]

Ok, I'd like too to defer addressing it to a follow-up PR and unblock this PR meantime.

[leogr]

LGTM.

/hold for a 2nd thought from previous reviewers

[poiana]

LGTM label has been added.

Git tree hash: c3384235c7b420e327935c106e75e6076e4729b1

[leogr]

/unhold

[poiana]

LGTM label has been added.

Git tree hash: acd64616709c921d35287b4210895f0a0cfb9630

[poiana]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: leogr, mrgian

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• content/OWNERS [leogr]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment