diff options
| -rw-r--r-- | docs/env_variables.md | 8 | ||||
| -rw-r--r-- | docs/status_screen.md | 24 |
2 files changed, 32 insertions, 0 deletions
diff --git a/docs/env_variables.md b/docs/env_variables.md index 9d289f6d..ebb7521e 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -393,6 +393,14 @@ checks or alter some of the more exotic semantics of the tool: normally done when starting up the forkserver and causes a pretty significant performance drop. + - Setting AFL_STATSD enable StatsD metrics collection. + By default AFL will send these metrics over UDP to 127.0.0.1:8125. + The host and port are configurable with AFL_STATSD_HOST and AFL_STATSD_PORT + respectively. + To get the most out of this, you should provide AFL_STATSD_TAGS_FLAVOR that + matches your StatsD server. + Available flavors are `dogstatsd`, `librato`, `signalfx` and `influxdb`. + - Outdated environment variables that are that not supported anymore: AFL_DEFER_FORKSRV AFL_PERSISTENT diff --git a/docs/status_screen.md b/docs/status_screen.md index f7655bf4..0cede6ff 100644 --- a/docs/status_screen.md +++ b/docs/status_screen.md @@ -406,3 +406,27 @@ Most of these map directly to the UI elements discussed earlier on. On top of that, you can also find an entry called `plot_data`, containing a plottable history for most of these fields. If you have gnuplot installed, you can turn this into a nice progress report with the included `afl-plot` tool. + + +### Addendum: Automatically send metrics with StatsD + +In a CI environment or when running multiple fuzzers, it can be tedious to +log into each of them or deploy scripts to read the fuzzer statistics. +Using `AFL_STATSD` (and the other related environment variables `AFL_STATSD_HOST`, +`AFL_STATSD_PORT`, `AFL_STATSD_TAGS_FLAVOR`) you can automatically send metrics +to your favorite StatsD server. Depending on your StatsD server you will be able +to monitor, trigger alerts or perform actions based on these metrics (e.g: alert on +slow exec/s for a new build, threshold of crashes, time since last crash > X, etc). + +The selected metrics are a subset of all the metrics found in the status and in +the plot file. The list is the following: `cycle_done`, `cycles_wo_finds`, +`execs_done`,`execs_per_sec`, `paths_total`, `paths_favored`, `paths_found`, +`paths_imported`, `max_depth`, `cur_path`, `pending_favs`, `pending_total`, +`variable_paths`, `unique_crashes`, `unique_hangs`, `total_crashes`, +`slowest_exec_ms`, `edges_found`, `var_byte_count`, `havoc_expansion`. +Their definitions can be found in the addendum above. + +When using multiple fuzzer instances with StatsD it is *strongly* recommended to setup +the flavor (AFL_STATSD_TAGS_FLAVOR) to match your StatsD server. This will allow you +to see individual fuzzer performance, detect bad ones, see the progress of each +strategy... |