fix(falco): add missing fields to falco config

Added "outputs" field to falco configuration.

Signed-off-by: Aldo Lacuku <aldo@lacuku.eu>

falco/CHANGELOG.md

@@ -3,6 +3,10 @@
 This file documents all notable changes to Falco Helm Chart. The release
 numbering uses [semantic versioning](http://semver.org).
 
+## v3.6.0
+
+* Add `outputs`field to falco configuration
+
 ## v3.5.0
 
 ## Major Changes

falco/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: falco
-version: 3.5.0
+version: 3.6.0
 appVersion: "0.35.1"
 description: Falco
 keywords:

falco/generated/helm-values.md

@@ -1,5 +1,5 @@
 # Configuration values for falco chart
-`Chart version: v3.4.1`
+`Chart version: v3.6.0`
 ## Values
 
 | Key | Type | Default | Description |
@@ -70,6 +70,7 @@
 | falco.metrics | object | `{"convert_memory_to_mb":true,"enabled":false,"include_empty_values":false,"interval":"1h","kernel_event_counters_enabled":true,"libbpf_stats_enabled":true,"output_rule":true,"resource_utilization_enabled":true}` | - [Usage]  `enabled`: Disabled by default.  `interval`: The stats interval in Falco follows the time duration definitions used by Prometheus. https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations  Time durations are specified as a number, followed immediately by one of the following units:  ms - millisecond s - second m - minute h - hour d - day - assuming a day has always 24h w - week - assuming a week has always 7d y - year - assuming a year has always 365d  Example of a valid time duration: 1h30m20s10ms  A minimum interval of 100ms is enforced for metric collection. However, for production environments, we recommend selecting one of the following intervals for optimal monitoring:  15m 30m 1h 4h 6h  `output_rule`: To enable seamless metrics and performance monitoring, we recommend emitting metrics as the rule "Falco internal: metrics snapshot". This option is particularly useful when Falco logs are preserved in a data lake. Please note that to use this option, the Falco rules config `priority` must be set to `info` at a minimum.  `output_file`: Append stats to a `jsonl` file. Use with caution in production as Falco does not automatically rotate the file.  `resource_utilization_enabled`: Emit CPU and memory usage metrics. CPU usage is reported as a percentage of one CPU and can be normalized to the total number of CPUs to determine overall usage. Memory metrics are provided in raw units (`kb` for `RSS`, `PSS` and `VSZ` or `bytes` for `container_memory_used`) and can be uniformly converted to megabytes (MB) using the `convert_memory_to_mb` functionality. In environments such as Kubernetes, it is crucial to track Falco's container memory usage. To customize the path of the memory metric file, you can create an environment variable named `FALCO_CGROUP_MEM_PATH` and set it to the desired file path. By default, Falco uses the file `/sys/fs/cgroup/memory/memory.usage_in_bytes` to monitor container memory usage, which aligns with Kubernetes' `container_memory_working_set_bytes` metric.  `kernel_event_counters_enabled`: Emit kernel side event and drop counters, as an alternative to `syscall_event_drops`, but with some differences. These counters reflect monotonic values since Falco's start and are exported at a constant stats interval.  `libbpf_stats_enabled`: Exposes statistics similar to `bpftool prog show`, providing information such as the number of invocations of each BPF program attached by Falco and the time spent in each program measured in nanoseconds. To enable this feature, the kernel must be >= 5.1, and the kernel configuration `/proc/sys/kernel/bpf_stats_enabled` must be set. This option, or an equivalent statistics feature, is not available for non `*bpf*` drivers. Additionally, please be aware that the current implementation of `libbpf` does not support granularity of statistics at the bpf tail call level.  `include_empty_values`: When the option is set to true, fields with an empty numeric value will be included in the output. However, this rule does not apply to high-level fields such as `n_evts` or `n_drops`; they will always be included in the output even if their value is empty. This option can be beneficial for exploring the data schema and ensuring that fields with empty values are included in the output. todo: prometheus export option todo: syscall_counters_enabled option |
 | falco.modern_bpf | object | `{"cpus_for_each_syscall_buffer":2}` | - [Suggestions]  The default choice of index 2 (one syscall buffer for each CPU pair) was made because the modern bpf probe utilizes a different memory allocation strategy compared to the other two drivers (bpf and kernel module). However, you have the flexibility to experiment and find the optimal configuration for your system.  When considering a fixed syscall_buf_size_preset and a fixed buffer dimension: - Increasing this configs value results in lower number of buffers and you can   speed up your system and reduce memory usage - However, using too few buffers may increase contention in the kernel,   leading to a slowdown.  If you have low event throughputs and minimal drops, reducing the number of buffers (higher `cpus_for_each_syscall_buffer`) can lower the memory footprint. |
 | falco.output_timeout | int | `2000` | The `output_timeout` parameter specifies the duration, in milliseconds, to wait before considering the deadline exceeded. By default, the timeout is set to 2000ms (2 seconds), meaning that the consumer of Falco outputs can block the Falco output channel for up to 2 seconds without triggering a timeout error.  Falco actively monitors the performance of output channels. With this setting the timeout error can be logged, but please note that this requires setting Falco's operational logs `log_level` to a minimum of `notice`.  It's important to note that Falco outputs will not be discarded from the output queue. This means that if an output channel becomes blocked indefinitely, it indicates a potential issue that needs to be addressed by the user. |
+| falco.outputs | object | `{"max_burst":1000,"rate":0}` | A throttling mechanism, implemented as a token bucket, can be used to control the rate of Falco outputs. Each event source has its own rate limiter, ensuring that alerts from one source do not affect the throttling of others. The following options control the mechanism:  - rate: the number of tokens (i.e. right to send a notification) gained per    second. When 0, the throttling mechanism is disabled. Defaults to 0.  - max_burst: the maximum number of tokens outstanding. Defaults to 1000.  For example, setting the rate to 1 allows Falco to send up to 1000 notifications initially, followed by 1 notification per second. The burst capacity is fully restored after 1000 seconds of no activity.  Throttling can be useful in various scenarios, such as preventing notification floods, managing system load, controlling event processing, or complying with rate limits imposed by external systems or APIs. It allows for better resource utilization, avoids overwhelming downstream systems, and helps maintain a balanced and controlled flow of notifications.  With the default settings, the throttling mechanism is disabled. |
 | falco.plugins | list | `[{"init_config":null,"library_path":"libk8saudit.so","name":"k8saudit","open_params":"http://:9765/k8s-audit"},{"library_path":"libcloudtrail.so","name":"cloudtrail"},{"init_config":"","library_path":"libjson.so","name":"json"}]` | Customize subsettings for each enabled plugin. These settings will only be applied when the corresponding plugin is enabled using the `load_plugins` option. |
 | falco.priority | string | `"debug"` | Any rule with a priority level more severe than or equal to the specified minimum level will be loaded and run by Falco. This allows you to filter and control the rules based on their severity, ensuring that only rules of a certain priority or higher are active and evaluated by Falco. Supported levels: "emergency", "alert", "critical", "error", "warning", "notice", "info", "debug" |
 | falco.program_output | object | `{"enabled":false,"keep_alive":false,"program":"jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"}` | Redirect the output to another program or command.  Possible additional things you might want to do with program output:   - send to a slack webhook:         program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"   - logging (alternate method than syslog):         program: logger -t falco-test   - send over a network connection:         program: nc host.example.com 80 If `keep_alive` is set to `true`, the program will be started once and continuously written to, with each output message on its own line. If `keep_alive` is set to `false`, the program will be re-spawned for each output message. Furthermore, the program will be re-spawned if Falco receives the SIGUSR1 signal. |

falco/values.yaml

@@ -592,6 +592,31 @@ falco:
   # output mechanism. By default, buffering is disabled (false).
   buffered_outputs: false
 
+  # [Stable] `outputs`
+  #
+  # -- A throttling mechanism, implemented as a token bucket, can be used to control
+  # the rate of Falco outputs. Each event source has its own rate limiter,
+  # ensuring that alerts from one source do not affect the throttling of others.
+  # The following options control the mechanism:
+  #  - rate: the number of tokens (i.e. right to send a notification) gained per
+  #    second. When 0, the throttling mechanism is disabled. Defaults to 0.
+  #  - max_burst: the maximum number of tokens outstanding. Defaults to 1000.
+  #
+  # For example, setting the rate to 1 allows Falco to send up to 1000
+  # notifications initially, followed by 1 notification per second. The burst
+  # capacity is fully restored after 1000 seconds of no activity.
+  #
+  # Throttling can be useful in various scenarios, such as preventing notification
+  # floods, managing system load, controlling event processing, or complying with
+  # rate limits imposed by external systems or APIs. It allows for better resource
+  # utilization, avoids overwhelming downstream systems, and helps maintain a
+  # balanced and controlled flow of notifications.
+  #
+  # With the default settings, the throttling mechanism is disabled.
+  outputs:
+    rate: 0
+    max_burst: 1000
+
   ##########################
   # Falco outputs channels #
   ##########################