X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=e831867a2fe7c5b9fe51f9008684c6a3a631d824;hp=39af988ed4fd17a2ffd350aa04598bff7e84e80b;hb=5975c30aac46bd29da9331652180a8de3c9e2d6e;hpb=05be38022cd7384a41303bbb88e16c479e2b5fd8 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 39af988ed..e831867a2 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -448,8 +448,9 @@ there is data available. .RE .PP -.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" -.nf +.PP +\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS] +.RS Enable tracing event A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is @@ -459,87 +460,104 @@ using the wildcard "*". If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-c, \-\-channel NAME" +Apply on channel name +.TP +.BR "\-a, \-\-all" +Enable all tracepoints and syscalls. This actually enable a single +wildcard event "*". +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.TP +.BR "\-\-tracepoint" +Tracepoint event (default). Userspace tracer supports wildcards at end +of string. Don't forget to quote to deal with bash expansion. +e.g.: .nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-c, \-\-channel NAME - Apply on channel name -\-a, \-\-all - Enable all tracepoints and syscalls. This actually enable a single - wildcard event "*". -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer - -\-\-tracepoint - Tracepoint event (default) - - userspace tracer supports wildcards at end of string. Don't forget to - quote to deal with bash expansion. - e.g.: "*" "app_component:na*" -\-\-loglevel NAME - Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). -\-\-loglevel-only NAME - Tracepoint loglevel (only this loglevel). - - The loglevel or loglevel-only options should be combined with a - tracepoint name or tracepoint wildcard. -\-\-probe [addr | symbol | symbol+offset] - Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) - or hexadecimal (0xNNN...) -\-\-function [addr | symbol | symbol+offset] - Dynamic function entry/return probe. Addr and offset can be octal - (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) -\-\-syscall - System call event. Enabling syscalls tracing (kernel tracer), you will - not be able to disable them with disable-event. This is a known - limitation. You can disable the entire channel to do the trick. - -\-\-filter 'expression' - Set a filter on a newly enabled event. Filter expression on event - fields and context. Event recording depends on evaluation. Only - specify on first activation of a given event within a session. - Filter only allowed when enabling events within a session before - tracing is started. If the filter fails to link with the event - within the traced domain, the event will be discarded. - Currently, filter is only implemented for the user-space tracer. - - Expression examples: - - 'intfield > 500 && intfield < 503' - '(stringfield == "test" || intfield != 10) && intfield > 33' - 'doublefield > 1.1 && intfield < 5.3' - - Wildcards are allowed at the end of strings: - 'seqfield1 == "te*"' - In string literals, the escape character is a '\\'. Use '\\*' for - the '*' character, and '\\\\' for the '\\' character. Wildcard - match any sequence of characters, including an empty sub-string - (match 0 or more characters). - - Context information can be used for filtering. The examples - below show usage of context filtering on process name (with a - wildcard), process ID range, and unique thread ID for filtering. - The process and thread ID of running applications can be found - under columns "PID" and "LWP" of the "ps -eLf" command. - - '$ctx.procname == "demo*"' - '$ctx.vpid >= 4433 && $ctx.vpid < 4455' - '$ctx.vtid == 1234' .fi +.TP +.BR "\-\-loglevel NAME" +Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h). +.TP +.BR "\-\-loglevel-only NAME" +Tracepoint loglevel (only this loglevel). +The loglevel or loglevel-only options should be combined with a +tracepoint name or tracepoint wildcard. +.TP +.BR "\-\-probe (addr | symbol | symbol+offset)" +Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) +or hexadecimal (0xNNN...) +.TP +.BR "\-\-function (addr | symbol | symbol+offset)" +Dynamic function entry/return probe. Addr and offset can be octal +(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) +.TP +.BR "\-\-syscall" +System call event. Enabling syscalls tracing (kernel tracer), you will +not be able to disable them with disable-event. This is a known +limitation. You can disable the entire channel to do the trick. +.TP +.BR "\-\-filter 'expression'" +Set a filter on a newly enabled event. Filter expression on event +fields and context. Event recording depends on evaluation. Only +specify on first activation of a given event within a session. +Filter only allowed when enabling events within a session before +tracing is started. If the filter fails to link with the event +within the traced domain, the event will be discarded. +Currently, filter is only implemented for the user-space tracer. + +Expression examples: -.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" .nf + 'intfield > 500 && intfield < 503' + '(strfield == "test" || intfield != 10) && intfield > 33' + 'doublefield > 1.1 && intfield < 5.3' +.fi + +Wildcards are allowed at the end of strings: + 'seqfield1 == "te*"' +In string literals, the escape character is a '\\'. Use '\\*' for +the '*' character, and '\\\\' for the '\\' character. Wildcard +match any sequence of characters, including an empty sub-string +(match 0 or more characters). + +Context information can be used for filtering. The examples below show +usage of context filtering on process name (with a wildcard), process ID +range, and unique thread ID for filtering. The process and thread ID of +running applications can be found under columns "PID" and "LWP" of the +"ps -eLf" command. + +.nf + '$ctx.procname == "demo*"' + '$ctx.vpid >= 4433 && $ctx.vpid < 4455' + '$ctx.vtid == 1234' +.fi + +.RE +.PP + +.PP +\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing channel Disabling a channel makes all event(s) in that channel to stop tracing. You can @@ -547,25 +565,30 @@ enable it back by calling \fBlttng enable-channel NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBdisable-event\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" -.nf +.PP +\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS] +.RS Disable tracing event The event, once disabled, can be re-enabled by calling \fBlttng enable-event @@ -573,28 +596,34 @@ NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-s, \-\-session NAME - Apply on session name -\-a, \-\-all-events - Disable all events. This does NOT disable "*" but rather - every known events of the session. -\-k, \-\-kernel - Apply for the kernel tracer -\-u, \-\-userspace - Apply for the user-space tracer -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-s, \-\-session NAME" +Apply on session name +.TP +.BR "\-a, \-\-all-events" +Disable all events. This does NOT disable "*" but rather every known +events of the session. +.TP +.BR "\-k, \-\-kernel" +Apply for the kernel tracer +.TP +.BR "\-u, \-\-userspace" +Apply for the user-space tracer +.RE +.PP -.IP "\fBlist\fP [\-k|\-u] [SESSION [SESSION_OPTIONS]]" -.nf +.PP +\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]] +.RS List tracing session information. With no arguments, it will list available tracing session(s). @@ -608,84 +637,96 @@ calls events). With \-u alone, it will list all available user-space events from registered applications. Here is an example of 'lttng list \-u': +.nf PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello ust_tests_hello:tptest_sighandler (type: tracepoint) ust_tests_hello:tptest (type: tracepoint) +.fi You can now enable any event listed by using the name : \fBust_tests_hello:tptest\fP. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-k, \-\-kernel - Select kernel domain -\-u, \-\-userspace - Select user-space domain. +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-k, \-\-kernel" +Select kernel domain +.TP +.BR "\-u, \-\-userspace" +Select user-space domain. +.PP .B SESSION OPTIONS: -\-c, \-\-channel NAME - List details of a channel -\-d, \-\-domain - List available domain(s) -.fi +.TP +.BR "\-c, \-\-channel NAME" +List details of a channel +.TP +.BR "\-d, \-\-domain" +List available domain(s) +.RE +.PP -.IP "\fBset-session\fP NAME" -.nf +.PP +\fBset-session\fP NAME [OPTIONS] +.RS Set current session name Will change the session name in the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBsnapshot\fP ACTION" -.nf +.PP +\fBsnapshot\fP [OPTIONS] ACTION +.RS Snapshot command for LTTng session. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.PP .B ACTION: -.nf +.TP \fBadd-output\fP [-m ] [-s ] [-n ] | -C -D Setup and add an snapshot output for a session. Output are the destination where the snapshot will be sent. Only one output is permitted. To change it, you'll need to delete it and add back the new one. +.TP \fBdel-output\fP ID | NAME [-s ] Delete an output for a session using the ID. You can either specify the output's ID that can be found with list-output or the name. +.TP \fBlist-output\fP [-s ] List the output of a session. Attributes of the output are printed. +.TP \fBrecord\fP [-m ] [-s ] [-n ] [ | -C -D ] Snapshot a session's buffer(s) for all domains. If an URL is specified, it is @@ -693,54 +734,59 @@ used instead of a previously added output. Specifying only a name or/and a max size will override the current output values. For instance, you can record a snapshot with a custom maximum size or with a different name. +.nf $ lttng add-output -n mysnapshot file:///data/snapshot [...] $ lttng snapshot record -n new_name_snapshot +.fi The above will create a snapshot in /data/snapshot/new_name_snapshot* directory rather then in mysnapshot*/ -.fi - -.B LONG OPTIONS -.nf -\-s, \-\-session NAME - Apply to session name. -\-n, \-\-name NAME - Name of the snapshot's output. -\-m, \-\-max-size SIZE - Maximum size in bytes of the snapshot. The maxium size does not - include the metadata file. -\-C, \-\-ctrl-url URL - Set control path URL. (Must use -D also) -\-D, \-\-data-url URL - Set data path URL. (Must use -C also) -.fi +.PP +.B DETAILED ACTION OPTIONS -.IP +.TP +.BR "\-s, \-\-session NAME" +Apply to session name. +.TP +.BR "\-n, \-\-name NAME" +Name of the snapshot's output. +.TP +.BR "\-m, \-\-max-size SIZE" +Maximum size in bytes of the snapshot. The maxium size does not include +the metadata file. +.TP +.BR "\-C, \-\-ctrl-url URL" +Set control path URL. (Must use -D also) +.TP +.BR "\-D, \-\-data-url URL" +Set data path URL. (Must use -C also) +.RE +.PP -.IP "\fBstart\fP [NAME] [OPTIONS]" -.nf +.PP +\fBstart\fP [NAME] [OPTIONS] +.RS Start tracing It will start tracing for all tracers for a specific tracing session. - If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.IP "\fBstop\fP [NAME] [OPTIONS]" -.nf +.PP +\fBstop\fP [NAME] [OPTIONS] +.RS Stop tracing It will stop tracing for all tracers for a specific tracing session. Before @@ -749,36 +795,35 @@ until the trace is readable for the session. Use \-\-no-wait to avoid this behavior. If NAME is omitted, the session name is taken from the .lttngrc file. -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -\-\-no-wait - Don't wait for data availability. -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.TP "\-\-no-wait" +Don't wait for data availability. +.RE +.PP -.IP "\fBversion\fP" -.nf +.PP +\fBversion\fP +.RS Show version information -.fi .B OPTIONS: -.nf -\-h, \-\-help - Show summary of possible options and commands. -\-\-list-options - Simple listing of options -.fi - -.IP +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP .IP "\fBview\fP [SESSION_NAME] [OPTIONS]" .nf