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. 11 12``` 13filter_command1 command_args 14filter_command2 command_args 15... 16``` 17 18### clock command 19 20``` 21CLOCK <clock_name> 22``` 23 24Set the clock used to generate timestamps in the filter file. Supported clocks are: `monotonic`, 25`realtime`. By default it is monotonic. The clock here should be the same as the clock used in 26profile data, which is set by `--clockid` in simpleperf record command. 27 28### global time filter commands 29 30``` 31GLOBAL_BEGIN <begin_timestamp> 32GLOBAL_END <end_timestamp> 33``` 34 35The nearest pair of GLOBAL_BEGIN and GLOBAL_END commands makes a time range. When these commands 36are used, only samples in the time ranges are reported. Timestamps are 64-bit integers in 37nanoseconds. 38 39``` 40GLOBAL_BEGIN 1000 41GLOBAL_END 2000 42GLOBAL_BEGIN 3000 43GLOBAL_BEGIN 4000 44``` 45 46For the example above, samples in time ranges [1000, 2000) and [3000, 4000) are reported. 47 48### process time filter commands 49 50``` 51PROCESS_BEGIN <pid> <begin_timestamp> 52PROCESS_END <pid> <end_timestamp> 53``` 54 55The nearest pair of PROCESS_BEGIN and PROCESS_END commands for the same process makes a time 56range. When these commands are used, each process has a list of time ranges, and only samples 57in the time ranges are reported. 58 59``` 60PROCESS_BEGIN 1 1000 61PROCESS_BEGIN 2 2000 62PROCESS_END 1 3000 63PROCESS_END 2 4000 64``` 65 66For the example above, process 1 samples in time range [1000, 3000) and process 2 samples in time 67range [2000, 4000) are reported. 68 69### thread time filter commands 70 71``` 72THREAD_BEGIN <tid> <begin_timestamp> 73THREAD_END <tid> <end_timestamp> 74``` 75 76The nearest pair of THREAD_BEGIN and THREAD_END commands for the same thread makes a time 77range. When these commands are used, each thread has a list of time ranges, and only samples in the 78time ranges are reported. 79 80``` 81THREAD_BEGIN 1 1000 82THREAD_BEGIN 2 2000 83THREAD_END 1 3000 84THREAD_END 2 4000 85``` 86 87For the example above, thread 1 samples in time range [1000, 3000) and thread 2 samples in time 88range [2000, 4000) are reported. 89