perf documentation: Add desription forHEADER_TRACING_DATA
PATCH 1/1 perf documentation: Add desription forHEADER_TRACING_DATA
Add description and layout in the perf.data file for the header part describing trace data used in commands perf record -e XXX
where XXX is a probe or tracepoint.
--- .../Documentation/perf.data-file-format.txt | 106 +++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-)
tools/perf/Documentation/perf.data-file-format.txt +105 -1
@@ -67,9 +67,113 @@ flags. These define the valid bits: HEADER_RESERVED = 0, /* always cleared */ HEADER_FIRST_FEATURE = 1, + HEADER_TRACING_DATA = 1, -Describe me. +The header consists of several entries of variable length such as file +contents of several trace files like 'header_page', 'header_event'. +Also complete probe/<event-name>/format files are included. +The numbers in parenthesis are structure members refered to later in +the description and example. + +struct tracing_data { + char birthday[3] = { 23, 8, 68 }; Eyecatcher + char tracing[12] = "tracing0.6"; Type and version + uint8_t bigendian; Big or little endian platform + uint8_t sizelong; Size of long in bytes + uint32_t pagesize: Pagesize in bytes + char hdr_page[12] = "header_page" Name of file (1) + uint64_t hdr_page_size; File size in bytes (1a) + char hdr_page_contents[hdr_page_size]; Contents of file (1b) + char hdr_event[13] = "header_event" Name of file (2) + uint64_t hdr_event_size; File size in bytes + char hdr_page_contents[hdr_event_size]; Contents of file + uint32_t ftrace_count; Number of ftrace entries (3) + struct { Size and content of file + uint64_t file_size; + char file_content[file_size] + } ftrace[ftrace_count] ftrace_count array elements + uint32_t event_types; Number of event types (4) + struct { + char name[]; Name, null terminatedg (5) + uint32_t count; Number of probes (6) + struct { + uint64_t file_size; (7) + char file_content[file_size]; (8) + }[count]; Count always > 0 or omitted + }[event_types]; + uint32_t proc_kallsyms_size; Always zero + uint64_t printk_file_size; File size in bytes (9) + char printk_format[printk_file_size]; Contents of file + uint64_t saved_cmdlines_size; File size in bytes (10) + char saved_cmdlines[saved_cmdlines_size]; Contents of file +}; + +The structure description is straight forward. It contains file name, size +and contents from +- /sys/kernel/debug/tracing/events/header_page (1, 1a, 1b) +and +- /sys/kernel/debug/tracing/events/header_event (2). + +This is followed by a variable length part of format files found in directory +/sys/kernel/debug/tracing//events/ftrace/*/format for events selected +by the perf record -e XXX commands. Note member 'ftrace_count' can be zero. + +Next are the number of probe types specified by the perf record -e XXXX +command (4). Each type has stored its name (5), which is a null terminated +string, and the number of probes (6) belonging to this type. For each +active probe follows the file size (7) and file contents (8) of that probe. + +Finally the file size and contents of two more files is saved: +- Size of /proc/kallsyms (always hard coded to zero and no file contents) +- /sys/kernel/debug/tracing/printk_formats (9) +- /sys/kernel/debug/tracing/saved_cmdlines (10) + +Example for the dynamic probes and trace points: +Consider these probes have been set up: + # ./perf probe -l + probe:vfs_getname (on getname_flags:72@fs/namei.c with pathname) + probe:xxx (on do_file_open_root:11@fs/namei.c) + # +and this command used for recording: + # ./perf record -e probe:vfs_getname -e probe:xxx \ + -e tcp:tcp_retransmit_skb -- touch /tmp/xxx + +This command line leads to two events in directory + /sys/kernel/debug/tracing/events/probe/vfs_getname + /sys/kernel/debug/tracing/events/probe/xxx +and a tracepoint in directory + /sys/kernel/debug/tracing/events/tcp/tcp_retransmit_skb. + +This results in this event_count (5) layout in the perf.data: +using command: + # od -Ax -t x4z -v perf.data + +0011a0 00000000 00000270 726f6265 00000000 >.......probe....< + ^^ (4)^^^'' ''(5)''' ''--(6)- + 4: # of types --> 2 + 5: first one named 'probe' + 6: 2 probes defined +0011b0 02000000 00000001 766e616d 653a2078 >........vname: x< + --###### (7)##### ## + 7: first one 'named' xxx with format file size 0x176 +0011c0 78780a49 443a2031 3138360a 666f726d >xx.ID: 1186.form< +... +001320 45432d3e 5f5f7072 6f62655f 69700a00 >EC->__probe_ip..< + '' +001330 00000000 0001e36e 616d653a 20766673 >.......name: vfs< + ''(7)''' '''''' + 7: second one named 'vfs_getname' with format file size 0x1e3 +001340 5f676574 6e616d65 0a49443a 20313138 >_getname.ID: 118< +... +001510 70617468 6e616d65 290a7463 70000000 >pathname).tcp...< + ''(5 )'--(6)- +001520 00010000 00000000 05696e61 6d653a20 >.........iname: < + ----#### (7)##### #### + 5: second event type named 'tcp' + 6: 1 probe defined + 7: size of format file 0x568 +001530 7463705f 72657472 616e736d 69745f73 >tcp_retransmit_s< HEADER_BUILD_ID = 2,
Signature · 1 line
2.23.0
Em Tue, Mar 03, 2020 at 08:08:46AM +0100, Thomas Richter escreveu:
Quoted 4 lines
Add description and layout in the perf.data file for the header part describing trace data used in commands perf record -e XXX
where XXX is a probe or tracepoint.
Did you write this from scratch? I was going thru it and couldn't find what that "Note member 'ftrace_count' can be zero." refers to, couldn't find this ftrace_counter, is this outdated?
[root@five ~]# find /sys/kernel/debug/tracing/events/ -type f | xargs grep ftrace_count [root@five ~]# find /sys/kernel/debug/tracing/events/ -name ftrace_count
[root@five ~]# uname -a
Linux five 5.5.5-200.fc31.x86_64 #1 SMP Wed Feb 19 23:28:07 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux [root@five ~]#
The part about using a probe and then go on dissecting it is really nice, I'll try reproducing it soon,
Thanks,
- Arnaldo
Quoted 127 lines
Signed-off-by Thomas Richter <[email protected]>--- .../Documentation/perf.data-file-format.txt | 106 +++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-)tools/perf/Documentation/perf.data-file-format.txt +105
-1@@ -67,9 +67,113 @@ flags. These define the valid bits: HEADER_RESERVED = 0, /* always cleared */ HEADER_FIRST_FEATURE = 1, + HEADER_TRACING_DATA = 1, -Describe me. +The header consists of several entries of variable length such as file +contents of several trace files like 'header_page', 'header_event'. +Also complete probe/<event-name>/format files are included. +The numbers in parenthesis are structure members refered to later in +the description and example. + +struct tracing_data { + char birthday[3] = { 23, 8, 68 }; Eyecatcher + char tracing[12] = "tracing0.6"; Type and version + uint8_t bigendian; Big or little endian platform + uint8_t sizelong; Size of long in bytes + uint32_t pagesize: Pagesize in bytes + char hdr_page[12] = "header_page" Name of file (1) + uint64_t hdr_page_size; File size in bytes (1a) + char hdr_page_contents[hdr_page_size]; Contents of file (1b) + char hdr_event[13] = "header_event" Name of file (2) + uint64_t hdr_event_size; File size in bytes + char hdr_page_contents[hdr_event_size]; Contents of file + uint32_t ftrace_count; Number of ftrace entries (3) + struct { Size and content of file + uint64_t file_size; + char file_content[file_size] + } ftrace[ftrace_count] ftrace_count array elements + uint32_t event_types; Number of event types (4) + struct { + char name[]; Name, null terminatedg (5) + uint32_t count; Number of probes (6) + struct { + uint64_t file_size; (7) + char file_content[file_size]; (8) + }[count]; Count always > 0 or omitted + }[event_types]; + uint32_t proc_kallsyms_size; Always zero + uint64_t printk_file_size; File size in bytes (9) + char printk_format[printk_file_size]; Contents of file + uint64_t saved_cmdlines_size; File size in bytes (10) + char saved_cmdlines[saved_cmdlines_size]; Contents of file +}; + +The structure description is straight forward. It contains file name, size +and contents from +- /sys/kernel/debug/tracing/events/header_page (1, 1a, 1b) +and +- /sys/kernel/debug/tracing/events/header_event (2). + +This is followed by a variable length part of format files found in directory +/sys/kernel/debug/tracing//events/ftrace/*/format for events selected +by the perf record -e XXX commands. Note member 'ftrace_count' can be zero. + +Next are the number of probe types specified by the perf record -e XXXX +command (4). Each type has stored its name (5), which is a null terminated +string, and the number of probes (6) belonging to this type. For each +active probe follows the file size (7) and file contents (8) of that probe. + +Finally the file size and contents of two more files is saved: +- Size of /proc/kallsyms (always hard coded to zero and no file contents) +- /sys/kernel/debug/tracing/printk_formats (9) +- /sys/kernel/debug/tracing/saved_cmdlines (10) + +Example for the dynamic probes and trace points: +Consider these probes have been set up: + # ./perf probe -l + probe:vfs_getname (on getname_flags:72@fs/namei.c with pathname) + probe:xxx (on do_file_open_root:11@fs/namei.c) + # +and this command used for recording: + # ./perf record -e probe:vfs_getname -e probe:xxx \ + -e tcp:tcp_retransmit_skb -- touch /tmp/xxx + +This command line leads to two events in directory + /sys/kernel/debug/tracing/events/probe/vfs_getname + /sys/kernel/debug/tracing/events/probe/xxx +and a tracepoint in directory + /sys/kernel/debug/tracing/events/tcp/tcp_retransmit_skb. + +This results in this event_count (5) layout in the perf.data: +using command: + # od -Ax -t x4z -v perf.data + +0011a0 00000000 00000270 726f6265 00000000 >.......probe....< + ^^ (4)^^^'' ''(5)''' ''--(6)- + 4: # of types --> 2 + 5: first one named 'probe' + 6: 2 probes defined +0011b0 02000000 00000001 766e616d 653a2078 >........vname: x< + --###### (7)##### ## + 7: first one 'named' xxx with format file size 0x176 +0011c0 78780a49 443a2031 3138360a 666f726d >xx.ID: 1186.form< +... +001320 45432d3e 5f5f7072 6f62655f 69700a00 >EC->__probe_ip..< + '' +001330 00000000 0001e36e 616d653a 20766673 >.......name: vfs< + ''(7)''' '''''' + 7: second one named 'vfs_getname' with format file size 0x1e3 +001340 5f676574 6e616d65 0a49443a 20313138 >_getname.ID: 118< +... +001510 70617468 6e616d65 290a7463 70000000 >pathname).tcp...< + ''(5 )'--(6)- +001520 00010000 00000000 05696e61 6d653a20 >.........iname: < + ----#### (7)##### #### + 5: second event type named 'tcp' + 6: 1 probe defined + 7: size of format file 0x568 +001530 7463705f 72657472 616e736d 69745f73 >tcp_retransmit_s< HEADER_BUILD_ID = 2,Signature · 1 line
2.23.0
Signature · 1 line
- Arnaldo
Quoted 16 lines · Arnaldo Carvalho de Melo
Em Tue, Mar 03, 2020 at 08:08:46AM +0100, Thomas Richter escreveu:
Quoted 4 lines
Add description and layout in the perf.data file for the header part describing trace data used in commands perf record -e XXX
where XXX is a probe or tracepoint.Did you write this from scratch? I was going thru it and couldn't find what that "Note member '
ftrace_count' can be zero." refers to, couldn't find thisftrace_counter, is this outdated?[root@five ~]# find
/sys/kernel/debug/tracing/events/-type f | xargs grepftrace_count[root@five ~]# find/sys/kernel/debug/tracing/events/-nameftrace_count
[root@five ~]# uname -a
Linux five 5.5.5-200.fc31.x86_64 #1 SMP Wed Feb 19 23:28:07 UTC 2020x86_64x86_64x86_64GNU/Linux [root@five ~]#
Quoted 5 lines
The part about using a probe and then go on dissecting it is really nice, I'll try reproducing it soon,
Thanks,
Arnaldo,
yes, I wrote this from scratch. I decided to invest some time into the documentation after I have spent nearly 3 week in debugging why commands
perf record -e probe:vfs_getname
followed by
perf report
did not print the file name on s390. Remember we talked about failing test case 65: Check open filename arg using perf trace + vfs_getname. (Steven Rostedt and Masami Hiramatsu helped me on this).
On ftrace_count: This is not a file available in /sys/kernel/debug/tracing. It is a value saved in function
tracing_data_get
record_ftrace_files
copy_event_system --> Check for some format file in directories
/sys/kernel/debug/tracing/events/ftrace/*/Depending on what probe was defined, there is no hit and zero is written to the output.
Hope this helps.
Signature · 5 lines
Thomas Richter, Dept 3252, IBM s390 Linux Development, Boeblingen, Germany -- Vorsitzender des Aufsichtsrats: Matthias Hartmann Geschäftsführung: Dirk Wittkopp Sitz der Gesellschaft: Böblingen / Registergericht: Amtsgericht Stuttgart, HRB 243294