1# Sample Filter 2 3Sometimes we want to report samples only for selected processes, threads, libraries, or time 4ranges. To filter samples, we can pass filter options to the report commands or scripts. 5 6 7## filter file format 8 9To filter samples based on time ranges, simpleperf accepts a filter file when reporting. The filter 10file is in text format, containing a list of lines. Each line is a filter command. The filter file 11can be generated by `sample_filter.py`, and passed to report scripts via `--filter-file`. 12 13``` 14filter_command1 command_args 15filter_command2 command_args 16... 17``` 18 19### clock command 20 21``` 22CLOCK <clock_name> 23``` 24 25Set the clock used to generate timestamps in the filter file. Supported clocks are: `monotonic`, 26`realtime`. By default it is monotonic. The clock here should be the same as the clock used in 27profile data, which is set by `--clockid` in simpleperf record command. 28 29### global time filter commands 30 31``` 32GLOBAL_BEGIN <begin_timestamp> 33GLOBAL_END <end_timestamp> 34``` 35 36The nearest pair of GLOBAL_BEGIN and GLOBAL_END commands makes a time range. When these commands 37are used, only samples in the time ranges are reported. Timestamps are 64-bit integers in 38nanoseconds. 39 40``` 41GLOBAL_BEGIN 1000 42GLOBAL_END 2000 43GLOBAL_BEGIN 3000 44GLOBAL_BEGIN 4000 45``` 46 47For the example above, samples in time ranges [1000, 2000) and [3000, 4000) are reported. 48 49### process time filter commands 50 51``` 52PROCESS_BEGIN <pid> <begin_timestamp> 53PROCESS_END <pid> <end_timestamp> 54``` 55 56The nearest pair of PROCESS_BEGIN and PROCESS_END commands for the same process makes a time 57range. When these commands are used, each process has a list of time ranges, and only samples 58in the time ranges are reported. 59 60``` 61PROCESS_BEGIN 1 1000 62PROCESS_BEGIN 2 2000 63PROCESS_END 1 3000 64PROCESS_END 2 4000 65``` 66 67For the example above, process 1 samples in time range [1000, 3000) and process 2 samples in time 68range [2000, 4000) are reported. 69 70### thread time filter commands 71 72``` 73THREAD_BEGIN <tid> <begin_timestamp> 74THREAD_END <tid> <end_timestamp> 75``` 76 77The nearest pair of THREAD_BEGIN and THREAD_END commands for the same thread makes a time 78range. When these commands are used, each thread has a list of time ranges, and only samples in the 79time ranges are reported. 80 81``` 82THREAD_BEGIN 1 1000 83THREAD_BEGIN 2 2000 84THREAD_END 1 3000 85THREAD_END 2 4000 86``` 87 88For the example above, thread 1 samples in time range [1000, 3000) and thread 2 samples in time 89range [2000, 4000) are reported. 90