# Sample Filter

Sometimes we want to report samples only for selected processes, threads, libraries, or time
ranges. To filter samples, we can pass filter options to the report commands or scripts.


## filter file format

To filter samples based on time ranges, simpleperf accepts a filter file when reporting. The filter
file is in text format, containing a list of lines. Each line is a filter command. The filter file
can be generated by `sample_filter.py` or `sample_filter_for_perfetto_trace.py`, and passed to
report scripts via `--filter-file`.

```
filter_command1 command_args
filter_command2 command_args
...
```

### clock command

```
CLOCK <clock_name>
```

Set the clock used to generate timestamps in the filter file. Supported clocks are: `monotonic`,
`realtime`. By default it is monotonic. The clock here should be the same as the clock used in
profile data, which is set by `--clockid` in simpleperf record command.

### global time filter commands

```
GLOBAL_BEGIN <begin_timestamp>
GLOBAL_END <end_timestamp>
```

The nearest pair of GLOBAL_BEGIN and GLOBAL_END commands makes a time range. When these commands
are used, only samples in the time ranges are reported. Timestamps are 64-bit integers in
nanoseconds.

```
GLOBAL_BEGIN 1000
GLOBAL_END 2000
GLOBAL_BEGIN 3000
GLOBAL_BEGIN 4000
```

For the example above, samples in time ranges [1000, 2000) and [3000, 4000) are reported.

### process time filter commands

```
PROCESS_BEGIN <pid> <begin_timestamp>
PROCESS_END <pid> <end_timestamp>
```

The nearest pair of PROCESS_BEGIN and PROCESS_END commands for the same process makes a time
range. When these commands are used, each process has a list of time ranges, and only samples
in the time ranges are reported.

```
PROCESS_BEGIN 1 1000
PROCESS_BEGIN 2 2000
PROCESS_END 1 3000
PROCESS_END 2 4000
```

For the example above, process 1 samples in time range [1000, 3000) and process 2 samples in time
range [2000, 4000) are reported.

### thread time filter commands

```
THREAD_BEGIN <tid> <begin_timestamp>
THREAD_END <tid> <end_timestamp>
```

The nearest pair of THREAD_BEGIN and THREAD_END commands for the same thread makes a time
range. When these commands are used, each thread has a list of time ranges, and only samples in the
time ranges are reported.

```
THREAD_BEGIN 1 1000
THREAD_BEGIN 2 2000
THREAD_END 1 3000
THREAD_END 2 4000
```

For the example above, thread 1 samples in time range [1000, 3000) and thread 2 samples in time
range [2000, 4000) are reported.
