diff options
author | Yabin Cui <yabinc@google.com> | 2022-01-06 14:48:48 -0800 |
---|---|---|
committer | Yabin Cui <yabinc@google.com> | 2022-01-07 11:27:11 -0800 |
commit | 9abea628d3b4770d325885881bc4c8a542aca3f6 (patch) | |
tree | e5c10b14f8ca86f636174374ea476f8c90ee506b /simpleperf/doc | |
parent | 13288de90836ee3e29642bc8c81940267d46fae8 (diff) | |
download | extras-9abea628d3b4770d325885881bc4c8a542aca3f6.tar.gz |
simpleperf: support filter file in RecordFilter.
filter file is used to filter samples based on time ranges.
Also add its format in doc/sample_filter.md.
Bug: 211814099
Test: run simpleperf_unit_test
Change-Id: Ic6eee3381ec005576d3f333fef502fffe7be59c2
Diffstat (limited to 'simpleperf/doc')
-rw-r--r-- | simpleperf/doc/sample_filter.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/simpleperf/doc/sample_filter.md b/simpleperf/doc/sample_filter.md new file mode 100644 index 00000000..3755e760 --- /dev/null +++ b/simpleperf/doc/sample_filter.md @@ -0,0 +1,88 @@ +# 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. + +``` +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. |