X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=089d87fa09861188d8e38551b1c4fde7b54829cf;hp=827c63c18132433028c7e165dcef400ed5736905;hb=9bd578f50a1e2438c40ca10789ca90d63c8f8829;hpb=1d76b9222464f9e10128ae867cd56a9317da5d65 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 827c63c18..089d87fa0 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,4 +1,4 @@ -.TH "LTTNG" "1" "February 9, 2012" "" "" +.TH "LTTNG" "1" "July 17, 2012" "" "" .SH "NAME" lttng \(em LTTng 2.0 tracer control command line tool @@ -17,7 +17,7 @@ It's tracers help tracking down performance issues and debugging problems involving multiple concurrent processes and threads. Tracing across multiple systems is also possible. -The \fBlttng\fP command line tool from lttng-tools package is used to control +The \fBlttng\fP command line tool from the lttng-tools package is used to control both kernel and user-space tracing. Every interactions with the tracer should be done by this tool or by the liblttng-ctl provided with the lttng-tools package. @@ -32,8 +32,8 @@ In order to trace the kernel, the session daemon needs to be running as root. LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is in that group can interact with the root session daemon and thus trace the kernel. Session daemons can co-exist meaning that you can have a session daemon -running as Alice that can be use to trace her applications along side with a -root daemon or even a Bob daemon. We highly recommand to start the session +running as Alice that can be used to trace her applications along side with a +root daemon or even a Bob daemon. We highly recommend to start the session daemon at boot time for stable and long term tracing. Every user-space applications instrumented with lttng-ust(3), will @@ -53,7 +53,8 @@ Show summary of possible options and commands. .TP .BR "\-v, \-\-verbose" Increase verbosity. -FIXME : details (\-v : sessiond verbose, \-vv : consumerd verbose, etc) ? +Three levels of verbosity are available which are triggered by putting additional v to +the option (\-vv or \-vvv) .TP .BR "\-q, \-\-quiet" Suppress all messages (even errors). @@ -205,7 +206,7 @@ aggregating multiple tracing sources. On creation, a \fB.lttngrc\fP file is created in your $HOME directory containing the current session name. If NAME is omitted, a session name is -automatically created having this form: 'auto-yyyymmdd-hhmms'. +automatically created having this form: 'auto-yyyymmdd-hhmmss'. If no \fB\-o, \-\-output\fP is specified, the traces will be written in $HOME/lttng-traces. @@ -238,6 +239,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .nf \-h, \-\-help Show summary of possible options and commands. +\-a, \-\-all + Destroy all sessions \-\-list-options Simple listing of options .fi @@ -248,6 +251,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .nf Enable tracing channel +To enable event, you must first enable a channel which contains event(s). + If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. .fi @@ -273,7 +278,7 @@ file. \-\-subbuf-size Subbuffer size in bytes (default: 4096, kernel default: 262144) \-\-num-subbuf - Number of subbufers (default: 4) + Number of subbuffers (default: 4) Needs to be a power of 2 for kernel and ust tracers \-\-switch-timer Switch subbuffer timer interval in usec (default: 0) @@ -335,6 +340,29 @@ file. 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, 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. + .fi .IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]" @@ -395,6 +423,10 @@ List tracing session information. With no arguments, it will list available tracing session(s). +With the session name, it will display the details of the session including +the trace file path, the associated channels and their state (activated +and deactivated), the activated events and more. + With \-k alone, it will list all available kernel events (except the system calls events). With \-u alone, it will list all available user-space events from registered @@ -416,7 +448,7 @@ You can now enable any event listed by using the name : \-\-list-options Simple listing of options \-k, \-\-kernel - Select kernel domain (FIXME : apparition de la notion de "domain" ici) + Select kernel domain \-u, \-\-userspace Select user-space domain. @@ -507,8 +539,8 @@ View traces of a tracing session By default, the babeltrace viewer will be used for text viewing. -The SESSION_NAME is an optional session name. If not specified, lttng will get -it from the configuration file (.lttngrc). +If SESSION_NAME is omitted, the session name is taken from the .lttngrc file. + .fi .B OPTIONS: @@ -528,6 +560,120 @@ it from the configuration file (.lttngrc). to the arguments .fi +.SH "EXIT VALUES" + +.IP "0" +Success + +.IP "1" +Command error + +.IP "2" +Undefined command + +.IP "3" +Fatal error + +.IP "4" +Command warning + +.IP "16" +No session found by the name given + +.IP "18" +Error in session creation + +.IP "21" +Error in application(s) listing + +.IP "28" +Session name already exists + +.IP "33" +Kernel tracer unavailable + +.IP "35" +Kernel event exists + +.IP "37" +Kernel channel exists + +.IP "38" +Kernel channel creation failed + +.IP "39" +Kernel channel not found + +.IP "40" +Kernel channel disable failed + +.IP "41" +Kernel channel enable failed + +.IP "42" +Kernel context failed + +.IP "43" +Kernel enable event failed + +.IP "44" +Kernel disable event failed + +.IP "53" +Kernel listing events failed + +.IP "60" +UST channel disable failed + +.IP "61" +UST channel enable failed + +.IP "62" +UST adding context failed + +.IP "63" +UST event enable failed + +.IP "64" +UST event disable failed + +.IP "66" +UST start failed + +.IP "67" +UST stop failed + +.IP "75" +UST event exists + +.IP "76" +UST event not found + +.IP "77" +UST context exists + +.IP "78" +UST invalid context + +.IP "79" +Tracing the kernel requires a root lttng-sessiond daemon and "tracing" group +user membership. + +.IP "80" +Tracing already started + +.IP "81" +Tracing already stopped + +.IP "98" +No UST consumer detected + +.IP "99" +No Kernel consumer detected + +.IP "100" +Event already enabled with different loglevel +.PP .SH "ENVIRONMENT VARIABLES" .PP @@ -535,7 +681,7 @@ Note that all command line options override environment variables. .PP .PP -.IP "LTTNG_SESSIOND_PATH_ENV" +.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. .SH "SEE ALSO" @@ -546,7 +692,7 @@ babeltrace(1), lttng-ust(3), lttng-sessiond(8) .SH "BUGS" .PP -No show stopper bugs known yet at this stable version. +No show stopper bugs are known yet in this version. If you encounter any issues or usability problem, please report it on our mailing list to help improve this project. @@ -570,7 +716,7 @@ You can find us on IRC server irc.oftc.net (OFTC) in #lttng. .PP Thanks to Yannick Brosseau without whom this project would never have been so lean and mean! Also thanks to the Ericsson teams working on tracing which -helped us greatly with detailled bug reports and unusual test cases. +helped us greatly with detailed bug reports and unusual test cases. Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA maintainer) and Jon Bernard for our Debian packages.