11# Coverage Filtering
22
3- ** ATTENTION:** This document describes an upcoming feature,
4- which is not yet released.
5-
6- Coverage recording for uninstrumented targets can be configured by a
3+ Coverage recording for _ uninstrumented_ targets can be configured by a
74user-provided _ filter list_ . By default, and if no list is provided, block
8- coverage is recorded for all runtime-observed modules and their identifiable
5+ coverage is recorded for all runtime-observed modules with identifiable
96function symbols.
107
118## Filter list format
@@ -21,13 +18,16 @@ The filter list is a JSON file that satisfies the following schema:
2118The filter list an array of objects that describe per-module rules.
2219
2320A ` <module-include> ` looks like:
21+
2422```
2523{
2624 "module": <regex>,
2725 "include": <Boolean | Array<regex>>
2826}
2927```
28+
3029And a ` <module-exclude> ` looks like:
30+
3131```
3232{
3333 "module": <regex>,
@@ -42,6 +42,7 @@ Note that the `module-` rules are polymorphic.
4242Filter rules are applied when the OneFuzz coverage recording code observes a
4343target load a new module. We must decide whether or not to record any coverage
4444for the module at all, and then for each function symbol that belongs to it.
45+ Per-function filtering is currently only implemented on Linux.
4546
4647By default, all modules and their symbols are _ included_ in coverage. When
4748module filter rules are present, the _ first applicable rule_ is used to filter a
9495 "include" : []
9596}
9697```
98+
9799We note this only for completeness. For these extreme cases, use the earlier boolean forms.
98100They are more direct and explicit, and help OneFuzz record coverage more efficiently.
99101
100102Note that the ` "module" ` property is also regex-valued.
101103Since OneFuzz tracks all available modules and symbols by default,
102104the (implicit) default rule could be written as:
105+
103106``` json
104107{
105108 "module" : " .*" ,
106109 "include" : true
107110}
108111```
112+
109113It is never necessary to write a rule equivalent to this.
110114However, this observation hints at how we can invert the default behavior!
111115If you want to exclude all modules by default, then we can add this rule to
112116the _ end_ of our filter list:
117+
113118``` json
114119{
115120 "module" : " .*" ,
116121 "exclude" : true
117122}
118123```
124+
119125As long as this is the last rule in our list, then any module not
120126filtered by some earlier rule will match this ` "module" ` regex, and thus be excluded.
0 commit comments