Update coverage filtering docs
# Coverage Filtering
-**ATTENTION:** This document describes an upcoming feature,
-which is not yet released.
-
-Coverage recording for uninstrumented targets can be configured by a
+Coverage recording for _uninstrumented_ targets can be configured by a
user-provided _filter list_. By default, and if no list is provided, block
-coverage is recorded for all runtime-observed modules and their identifiable
+coverage is recorded for all runtime-observed modules with identifiable
function symbols.
## Filter list format
@@ -21,13 +18,16 @@ The filter list is a JSON file that satisfies the following schema:
The filter list an array of objects that describe per-module rules.
A `<module-include>` looks like:
+
```
{
"module": <regex>,
"include": <Boolean | Array<regex>>
}
```
+
And a `<module-exclude>` looks like:
+
```
{
"module": <regex>,
@@ -42,6 +42,7 @@ Note that the `module-` rules are polymorphic.
Filter rules are applied when the OneFuzz coverage recording code observes a
target load a new module. We must decide whether or not to record any coverage
for the module at all, and then for each function symbol that belongs to it.
+Per-function filtering is currently only implemented on Linux.
By default, all modules and their symbols are _included_ in coverage. When
module filter rules are present, the _first applicable rule_ is used to filter a
@@ -94,27 +95,32 @@ Or:
"include": []
}
```
+
We note this only for completeness. For these extreme cases, use the earlier boolean forms.
They are more direct and explicit, and help OneFuzz record coverage more efficiently.
Note that the `"module"` property is also regex-valued.
Since OneFuzz tracks all available modules and symbols by default,
the (implicit) default rule could be written as:
+
```json
{
"module": ".*",
"include": true
}
```
+
It is never necessary to write a rule equivalent to this.
However, this observation hints at how we can invert the default behavior!
If you want to exclude all modules by default, then we can add this rule to
the _end_ of our filter list:
+
```json
{
"module": ".*",
"exclude": true
}
```
+
As long as this is the last rule in our list, then any module not
filtered by some earlier rule will match this `"module"` regex, and thus be excluded.
