diff options
Diffstat (limited to 'lket.5.in')
| -rw-r--r-- | lket.5.in | 274 |
1 files changed, 145 insertions, 129 deletions
@@ -29,6 +29,150 @@ user. Once the data has been collected, it is then post-processed according to the need of the user. Trace data can be processed in various different ways to generate simple to complex reports. +.SH TRACE DATA FORMAT + +By default, LKET will log the trace data in binary format. + +To get a better performance for binary tracing, the "\-b" option should +be turned on for stap and thus \-M option has to be added to stop staprun +merging per-cpu files. + +You could use the command +.I lket\-b2a +to convert the binary trace data +generated by LKET into readable data in ascii format. + +.I lket\-b2a +uses the pre-cpu binary trace data files(stpd_cpu*) as inputs, and generates +an output file named +.IR lket.out . +See +.IR lket-b2a (1) +manual page for more detail. + +If you want LKET to log trace data in ASCII format directly, you should: +.SAMPLE +stap \-D ASCII_TRACE ... +.ESAMPLE + +.SH EVENT REGISTER + +LKET provides a way to log the metadata of the trace data by events registering. + +Two function is provided: +.P +.IP +.SB register_sys_event(event_desc:string, grpid:long, hookid:long, fmt:string, names:string) +.IP +.SB register_user_event(grpid:long, hookid:long, fmt:string, names:string) +.P + +.I event_desc +is a string representation of the event, e.g: syscall.entry, scsi.iocompleted. + +.I grpid +and +.I hookid +is the groupid and hookid of the event to be registered. + +.I fmt +contains a set of fomat tokens seperated by ":". +The valid format tokens are: +.B UINT8, +.B UINT16, +.B UINT32, +.B UINT64 +and +.B STRING +which represents 8-bit, 16-bit, 32-bit, 64-bit binary data and NULL-terminated +respectively. + +.I names +contains a set of names seperated by ":". +The names contains in +.I names +should match the format tokens contains in +.I fmt + +.B register_sys_event +is used to register the newly added event hooks. For example, supposing you +want to add a new event hook to trace the entry of sys_open, and you want +this event hook to log the fd, flag and mode paremeters for you. You should +add: + +.SAMPLE +register_sys_event("iosyscall.open.entry", + GROUP_IOSYSCALL, HOOKID_IOSYSCALL_OPEN_ENTRY, + "STRING:INT32:INT32", "filename:flags:mode") +.ESAMPLE + +into the function +.B register_sys_events +in LKET/register_event.stp + + +.B register_user_event +is used for user to add extra trace data for a event hook. See +the section +.B CUSTOMIZED TRACE DATA +for more detail + + +.SH CUSTOMIZED TRACE DATA + +LKET provides a set of event hooks that log the predefined +trace data for you, but LKET also make you able to log extra +trace data for a event. + +LKET provides a way to do this without modifying the tapset +of that event hook. You can simply use printf to trace +extra data. For example, supposing you want to trace sk_buff\->mac_len +and sk_buff\->priority besides the sk_buff\->len, sk_buff\->protocol and +sk_buff\->truesize for the +.B netdev +event hooks: + +.SAMPLE +probe register_event +{ + register_user_event(GROUP_NETDEV, HOOKID_NETDEV_TRANSMIT, + "INT32:INT32", "mac_len:priority") +} +probe addevent.netdev.transmit +{ + printf("%4b%4b", $skb\->mac_len, $skb\->priority) +} +.ESAMPLE + +.SH EXAMPLES + +Here are some examples of using LKET: + +.TP +Trace all events provided by LKET: +stap \-e "probe addevent.* {}" \-bM + +.TP +Trace all available events by skipping those unavaiabled on current system: +stap \-e "probe addevent.* ? {}" \-bM + +.TP +Trace all system calls: +stap \-e "probe addevent.syscall {}" \-bM +.TP +Trace the entry of all system calls: +stap \-e "probe addevent.syscall.entry {}" \-bM +.TP +Trace netdev transmition and log extra data of mac_len and priority: +stap \-e "probe addevent.netdev.transmit { printf(\\"%4b%4b\\", $skb\->mac_len, $skb\->priority) }" \-bM + +.P +You can press "Ctrl+c" to stop the tracing. Then you will find there are one or more per-cpu data files (stpd_cpu*) on current directory. You can use +.I lket-b2a +to convert these binary trace data files into readable ascii format or dump them into database. See +.IR lket-b2a (1) +man page for more detail. + .SH EVENT HOOKS The following sections enumerate the variety of event hooks implemented @@ -1288,134 +1432,6 @@ Data format is: .I fh_size(INT8), fhandle0(INT64), fhandle1(INT64), fhandle2(INT64), version(INT8) .I filename(STRING) -.SH TRACE DATA FORMAT - -By default, LKET will log the trace data in binary format. - -To get a better performance for binary tracing, the "\-b" option should -be turned on for stap and thus \-M option has to be added to stop staprun -merging per-cpu files. - -You could use the command -.I lket\-b2a -to convert the binary trace data -generated by LKET into readable data in ascii format. - -.I lket\-b2a -uses the pre-cpu binary trace data files as inputs, and generates -an output file named -.I lket.out -You should use "stap \-b \-M" with LKET to get those pre-cpu files -(stpd_cpu*) before using it. - -If you want LKET to log trace data in ASCII format directly, you should: -.SAMPLE -stap \-D ASCII_TRACE ... -.ESAMPLE - -.SH EVENT REGISTER - -LKET provides a way to log the metadata of the trace data by events registering. - -Two function is provided: -.P -.IP -.SB register_sys_event(grpid:long, hookid:long, fmt:string, names:string) -.IP -.SB register_user_event(grpid:long, hookid:long, fmt:string, names:string) -.P - -The -.I grpid -and -.I hookid -is the groupid and hookid of the event you want to register. - -.I fmt -contains a set of fomat tokens seperated by ":". -The valid format tokens are: -.B UINT8, -.B UINT16, -.B UINT32, -.B UINT64 -and -.B STRING -which represents 8-bit, 16-bit, 32-bit, 64-bit binary data and NULL-terminated -respectively. - -.I names -contains a set of names seperated by ":". -The names contains in -.I names -should match the format tokens contains in -.I fmt - -.B register_sys_event -is used to register the newly added event hooks. For example, supposing you -want to add a new event hook to trace the entry of sys_open, and you want -this event hook to log the fd, flag and mode paremeters for you. You should -add: - -.SAMPLE -register_sys_event(GROUP_IOSYSCALL, HOOKID_IOSYSCALL_OPEN_ENTRY, - "STRING:INT32:INT32", "filename:flags:mode") -.ESAMPLE - -into the function -.B register_sys_events -in LKET/register_event.stp - - -.B register_user_event -is used for user to add extra trace data for a event hook. See -the section -.B CUSTOMIZED TRACE DATA -for more detail - - -.SH CUSTOMIZED TRACE DATA - -LKET defines a set of event hooks and will log the predefined -trace data for you, but what if you want to trace extra -data for that event? - -LKET provides a way to do this without modifying the codes in -the tapset of that event hook. You can simply use printf to trace -extra data. For example, supposing you want to trace sk_buff\->mac_len -and sk_buff\->priority besides the sk_buff\->len, sk_buff\->protocol and -sk_buff\->truesize for the -.B netdev -event hooks: - -.SAMPLE -probe register_event -{ - register_user_event(GROUP_NETDEV, HOOKID_NETDEV_TRANSMIT, - "INT32:INT32", "mac_len:priority") -} -probe addevent.netdev.transmit -{ - printf("%4b%4b", $skb\->mac_len, $skb\->priority) -} -.ESAMPLE - -.SH EXAMPLES - -Here are some examples of using LKET: - -.TP -To turn on all event hooks: -stap \-e "probe addevent.* {}" \-bM -.TP -To probe syscall: -stap \-e "probe addevent.syscall {}" \-bM -.TP -To only probe syscall.entry: -stap \-e "probe addevent.syscall.entry {}" \-bM -.TP -To probe netdev transmition and log extra data of mac_len and priority: -stap \-e "probe addevent.netdev.transmit { printf(\\"%4b%4b\\", $skb\->mac_len, $skb\->priority) }" \-bM - .SH SEE ALSO .IR stap (1) -.IR lket-b2a (5) +.IR lket-b2a (1) |