update: address some review comments

Signed-off-by: Andrea Terzolo <andrea.terzolo@polito.it>
Co-authored-by: Leonardo Grasso <me@leonardograsso.com>
Co-authored-by: Melissa Kilby <melissa.kilby.oss@gmail.com>

falco.yaml

@@ -211,18 +211,18 @@ syscall_event_timeouts:
 #
 # --- [Suggestions]
 #
-# Before the introduction of this param the buffer size was fixed to 8 MB (so index `4`, as you can see 
+# Before the introduction of this param the buffer size was fixed to 8 MB (so index `4`, as you can see
 # in the default value below).
-# Unless you are sure about what you are doing please keep this value as it is, Falco should work as
-# well as it always has with this value!
-# You can try to increase the buffer size when you face a lot of syscalls drops, but remember that this has
-# a price, larger buffers could slow down the entire machine. Moreover, consider that the buffer size is mapped
-# twice in the process' virtual memory so a buffer of 8 MB will result in a 16 MB area in the process virtual memory.
+# You can increase the buffer size when you face syscall drops. A size of 16 MB (so index `5`) can reduce
+# syscall drops in production-heavy systems without noticeable impact. Very large buffers however could
+# slow down the entire machine.
 # On the other side you can try to reduce the buffer size to speed up the system, but this could
 # increase the number of syscall drops!
-# So just to conclude, change this index only if you have the necessity otherwise leave it as it is!
+# As a final remark consider that the buffer size is mapped twice in the process' virtual memory so a buffer of 8 MB
+# will result in a 16 MB area in the process virtual memory.
+# Please pay attention when you use this parameter and change it only if the default size doesn't fit your use case.
 
-syscall_buffer_index: 4
+syscall_buf_size_preset: 4
 
 # Falco continuously monitors outputs performance. When an output channel does not allow
 # to deliver an alert within a given deadline, an error is reported indicating

userspace/falco/app_actions/compute_syscall_buffer_size.cpp

@@ -33,7 +33,7 @@ application::run_result application::configure_syscall_buffer_size()
 		return run_result::ok();
 	}
 
-	uint16_t index = m_state->config->m_syscall_buffer_index;
+	uint16_t index = m_state->config->m_syscall_buf_size_preset;
 	if(index < MIN_INDEX || index > MAX_INDEX)
 	{
 		return run_result::fatal("The index must be between '" + std::to_string(MIN_INDEX) + "' and '" + std::to_string(MAX_INDEX) + "'\n");

userspace/falco/app_cmdline_options.cpp

@@ -204,7 +204,7 @@ void cmdline_options::define()
 		("V,validate",                    "Read the contents of the specified rules(s) file and exit. Can be specified multiple times to validate multiple files.", cxxopts::value(validate_rules_filenames), "<rules_file>")
 		("v",                             "Verbose output.", cxxopts::value(verbose)->default_value("false"))
 		("version",                       "Print version number.", cxxopts::value(print_version_info)->default_value("false"))
-		("page-size",                     "Print the system page size used to choose the syscall buffer size.", cxxopts::value(print_page_size)->default_value("false"));
+		("page-size",                     "Print the system page size (may help you to choose the right syscall buffer size).", cxxopts::value(print_page_size)->default_value("false"));
 
 
 	m_cmdline_opts.set_width(140);

userspace/falco/configuration.cpp

@@ -288,7 +288,7 @@ void falco_configuration::init(string conf_filename, const vector<string> &cmdli
 	/* We put this value in the configuration file because in this way we can change the dimension at every reload.
 	 * The default value is `4` -> 8 MB.
 	 */
-	m_syscall_buffer_index = m_config->get_scalar<uint64_t>("syscall_buffer_index", 4);
+	m_syscall_buf_size_preset = m_config->get_scalar<uint64_t>("syscall_buf_size_preset", 4);
 
 	std::set<std::string> load_plugins;
 

userspace/falco/configuration.h

@@ -270,7 +270,7 @@ public:
 	uint32_t m_metadata_download_watch_freq_sec;
 
 	// Index corresponding to the syscall buffer dimension.
-	uint64_t m_syscall_buffer_index;
+	uint64_t m_syscall_buf_size_preset;
 
 	std::vector<plugin_config> m_plugins;