X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=57c89f0fa96b99851d8e9093e0f8c42af6fc293b;hp=96251b7980dbc6f2483bbf8aa43342cb22503177;hb=a8f307d87d2d308671df9fed0855f4344c60d335;hpb=272c6a17c172f26a8a6401703b1b46edb4b236e2 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 96251b798..57c89f0fa 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,4 +1,4 @@ -.TH "LTTNG" "1" "December 3rd, 2012" "" "" +.TH "LTTNG" "1" "July 18th, 2013" "" "" .SH "NAME" lttng \(em LTTng 2.x tracer control command line tool @@ -6,9 +6,7 @@ lttng \(em LTTng 2.x tracer control command line tool .SH "SYNOPSIS" .PP -.nf lttng [OPTIONS] -.fi .SH "DESCRIPTION" .PP @@ -216,7 +214,7 @@ Dynamic function entry/return probe (default) .PP .PP -.IP \fBcreate\fP [NAME] [OPTIONS] +\fBcreate\fP [NAME] [OPTIONS] .RS Create tracing session. @@ -249,7 +247,7 @@ Simple listing of options Specify output path for traces .TP .BR "\-\-no-output" -Traces will not be outputed +Traces will not be outputted .TP .BR "\-\-snapshot" Set the session in snapshot mode. Created in no-output mode and uses the @@ -455,8 +453,10 @@ Enable tracing event A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is omitted, a default channel named '\fBchannel0\fP' is created and the event is -added to it. For the user-space tracer, using \fB\-a, \-\-all\fP is the same as -using the wildcard "*". +added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default +channel already exists within the session, an error is returned. For the +user-space tracer, using \fB\-a, \-\-all\fP is the same as using the +wildcard "*". If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. @@ -586,8 +586,9 @@ 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 @@ -595,28 +596,41 @@ NAME\fP again. If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. -.fi + +If \fB\-c, \-\-channel\fP is omitted, the default channel name is used. +If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already +exists within the session, an error is returned. .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 "\-c, \-\-channel NAME" +Apply on channel 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). @@ -630,84 +644,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 @@ -715,54 +741,60 @@ 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. Human readable format is accepted: {+k,+M,+G}. For instance, +\-\-max-size 5M +.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 @@ -771,75 +803,75 @@ 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 - -.IP "\fBview\fP [SESSION_NAME] [OPTIONS]" -.nf -View traces of a tracing session - -By default, the babeltrace viewer will be used for text viewing. - -If SESSION_NAME is omitted, the session name is taken from the .lttngrc file. +.TP +.BR "\-h, \-\-help" +Show summary of possible options and commands. +.TP +.BR "\-\-list-options" +Simple listing of options +.RE +.PP -.fi +.PP +\fBview\fP [SESSION_NAME] [OPTIONS] +.RS +View traces of a tracing session. By default, the babeltrace viewer +will be used for text viewing. If SESSION_NAME is omitted, the session +name is taken from the .lttngrc file. .B OPTIONS: -.nf -\-h, \-\-help - Show this help -\-\-list-options - Simple listing of options -\-t, \-\-trace-path PATH - Trace directory path for the viewer -\-e, \-\-viewer CMD - Specify viewer and/or options to use - This will completely override the default viewers so - please make sure to specify the full command. The trace - directory path of the session will be appended at the end - to the arguments -.fi +.TP +.BR "\-h, \-\-help" +Show this help +.TP +.BR "\-\-list-options" +Simple listing of options +.TP +.BR "\-t, \-\-trace-path PATH" +Trace directory path for the viewer +.TP +.BR "\-e, \-\-viewer CMD" +Specify viewer and/or options to use This will completely override the +default viewers so please make sure to specify the full command. The +trace directory path of the session will be appended at the end to the +arguments +.RE +.PP .SH "EXIT VALUES" +.PP On success 0 is returned and a positive value on error. Value of 1 means a command error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that something went wrong during the command. Any other value above 10, please refer to -.BR +.BR "" for a detailed list or use lttng_strerror() to get a human readable string of the error code. - .PP + .SH "ENVIRONMENT VARIABLES" .PP @@ -850,17 +882,23 @@ Note that all command line options override environment variables. .IP "LTTNG_SESSIOND_PATH" Allows one to specify the full session daemon binary path to lttng command line tool. You can also use \-\-sessiond-path option having the same effect. +.PP + .SH "SEE ALSO" .BR babeltrace(1), .BR lttng-ust(3), .BR lttng-sessiond(8), .BR lttng-relayd(8), .BR lttng-health-check(3) + .SH "BUGS" +.PP If you encounter any issues or usability problem, please report it on our mailing list to help improve this project or at https://bugs.lttng.org which is a bugtracker. +.PP + .SH "CREDITS" .PP