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

Update coverage filtering docs #1950

Merged
merged 1 commit into from
May 16, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 11 additions & 5 deletions docs/how-to/coverage-filtering.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
# 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
Expand All @@ -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>,
Expand All @@ -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
Expand Down Expand Up @@ -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.