docs(README.md): add benchmark section and general improvements

Signed-off-by: Leonardo Grasso <me@leonardograsso.com>

README.md

@@ -59,7 +59,7 @@ syscall.WriteBelowRpmDatabase
 ```
 event-generator run [regexp]
 ```
-Without arguments it runs all actions, otherwise only those actions matching the given regular expression.
+Without arguments, it runs all actions; otherwise, only those actions matching the given regular expression.
 
 For example, to run `syscall.MkdirBinaryDirs` and
 `syscall.ModifyBinaryDirs` actions only:
@@ -109,12 +109,12 @@ kubectl apply -f deployment/event-generator.yaml
 ```
 
 **N.B.**
-The above commands apply to the `default` namespace. Use the `--namespace` option to use a different namespace. Events will be generated in the same namespace.
+The above commands apply to the `default` namespace. Use the `--namespace` option to use a different namespace. It will generate events in the same namespace.
 
 ## Collections
 
 ### Generate System Call activity
-The `syscall` collection performs a variety of suspect actions that are detected by the [default Falco ruleset](https://github.com/falcosecurity/falco/blob/master/rules/falco_rules.yaml).
+The `syscall` collection performs a variety of suspect actions detected by the [default Falco ruleset](https://github.com/falcosecurity/falco/blob/master/rules/falco_rules.yaml).
 
 ```shell
 $ docker run -it --rm falcosecurity/event-generator run syscall --loop
@@ -141,7 +141,7 @@ The above command loops forever, creating resources in the `falco-eg-sandbox` na
 
 ## Test rules
 
-Since `v0.4.0`, this tool introduces a convenient integration test suite for Falco rules. Basically the `event-generator test` command can run actions and test them against a running Falco instance.
+Since `v0.4.0`, this tool introduces a convenient integration test suite for Falco rules. The `event-generator test` command can run actions and test them against a running Falco instance.
 
 > This feature requires Falco 0.24.0 or newer. Before using the command below, you need [Falco installed](https://falco.org/docs/installation/) and running with the [gRPC Output](https://falco.org/docs/grpc/) enabled.
 
@@ -169,15 +169,47 @@ kubectl apply -f deployment/run-test.yaml
 
 Note that to test `k8saudit` events, you need [Kubernetes audit log] enabled both in Kubernetes and Falco.
 
+## Benchmark
+
+Since `v0.5.0`, the `event-generator` can also be used for benchmarking a running instance of Falco. The command `event-generator bench` generates a high number of Event Per Second (EPS) to show you events throughput allowed by your Falco installation.
+
+> This feature requires Falco 0.24.0 or newer. Before using the command in the section below, you need [Falco installed](https://falco.org/docs/installation/) and running with the [gRPC Output](https://falco.org/docs/grpc/) enabled.
+
+Finally, be aware that Falco embeds a rate-limiter for notifications that affect the gRPC Outputs APIs too. You probably need to increase the `outputs.rate` and `outputs.max_burst` values [within the Falco configuration](https://github.com/falcosecurity/falco/blob/e2bf87d207a32401da271835e15dadf957f68e8c/falco.yaml#L90-L104), otherwise EPS will be rate-limited by the throttling mechanism.
+
+### Run a benchmark
+
+Before starting a benchmark, the most important thing to understand is that the `--sleep` option controls the number of EPS (default to `250ms`): reducing this value will increase the EPS. Furthermore, if the `--loop` option is set, the sleeping duration is automatically halved on each round. The `--pid` option can be used to monitor the Falco process. 
+
+> You can find more details about the command-line usage [here](docs/event-generator_bench.md).
+
+Please, keep in mind that not all actions can be used for benchmarking since some of them take too long to generate a high number of EPS. For example, `k8saudit` actions are not supposed to work, since those actions need some time to create Kubernetes resources. Also, some `syscall` actions sleep for a while (like the [syscall.ReadSensitiveFileUntrusted](https://github.com/falcosecurity/event-generator/blob/7bf714aab8da5a3f6d930225f04852e97d682dac/events/syscall/read_sensitive_file_trusted_after_startup.go#L10)) thus cannot be used.
+
+**Benchmark example**
+
+Once you have relaxed the rate-limiter in the Falco configuration, for example by setting:
+
+```yaml
+outputs:
+  rate: 1000000000
+  max_burst: 1000000000
+```
+
+Then, a common way for benchmarking a local Falco instance is by running the following command (that connects via Unix socket to `/var/run/falco.sock` by default):
+
+```shell
+sudo event-generator bench "ChangeThreadNamespace|ReadSensitiveFileUntrusted|WriteBelowBinaryDir" --loop --pid $(ps -ef | awk '$8=="falco" {print $2}')
+```
+
 ## FAQ
 
-### What sample events can be generated by this tool?
+### What sample events can this tool generate?
 See the [events registry](https://github.com/falcosecurity/event-generator/tree/master/events).
 
 ### Can I contribute by adding new events?
 Sure! 
 
-Check out the [events registry](https://github.com/falcosecurity/event-generator/tree/master/events) conventions, then feel free to open a PR.
+Check out the [events registry](https://github.com/falcosecurity/event-generator/tree/master/events) conventions, then feel free to open a P.R.
 
 Your contribution is highly appreciated.