Skip to content
This repository was archived by the owner on Nov 1, 2023. It is now read-only.

Commit 02477b2

Browse files
authored
Update coverage filtering docs (#1950)
1 parent 4ee967a commit 02477b2

File tree

1 file changed

+11
-5
lines changed

1 file changed

+11
-5
lines changed

docs/how-to/coverage-filtering.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
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
74
user-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
96
function symbols.
107

118
## Filter list format
@@ -21,13 +18,16 @@ The filter list is a JSON file that satisfies the following schema:
2118
The filter list an array of objects that describe per-module rules.
2219

2320
A `<module-include>` looks like:
21+
2422
```
2523
{
2624
"module": <regex>,
2725
"include": <Boolean | Array<regex>>
2826
}
2927
```
28+
3029
And a `<module-exclude>` looks like:
30+
3131
```
3232
{
3333
"module": <regex>,
@@ -42,6 +42,7 @@ Note that the `module-` rules are polymorphic.
4242
Filter rules are applied when the OneFuzz coverage recording code observes a
4343
target load a new module. We must decide whether or not to record any coverage
4444
for 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

4647
By default, all modules and their symbols are _included_ in coverage. When
4748
module filter rules are present, the _first applicable rule_ is used to filter a
@@ -94,27 +95,32 @@ Or:
9495
"include": []
9596
}
9697
```
98+
9799
We note this only for completeness. For these extreme cases, use the earlier boolean forms.
98100
They are more direct and explicit, and help OneFuzz record coverage more efficiently.
99101

100102
Note that the `"module"` property is also regex-valued.
101103
Since OneFuzz tracks all available modules and symbols by default,
102104
the (implicit) default rule could be written as:
105+
103106
```json
104107
{
105108
"module": ".*",
106109
"include": true
107110
}
108111
```
112+
109113
It is never necessary to write a rule equivalent to this.
110114
However, this observation hints at how we can invert the default behavior!
111115
If you want to exclude all modules by default, then we can add this rule to
112116
the _end_ of our filter list:
117+
113118
```json
114119
{
115120
"module": ".*",
116121
"exclude": true
117122
}
118123
```
124+
119125
As long as this is the last rule in our list, then any module not
120126
filtered by some earlier rule will match this `"module"` regex, and thus be excluded.

0 commit comments

Comments
 (0)