X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1;h=f773e61f89b7659ad95a5f2a8d9645d3c1ff0864;hp=468ed69400edf31285f8a5061c7cd1bbfaf7f9ad;hb=c56509420616421ef4f6fff53e1cf09f3ccd56b7;hpb=6b8f2e642cddf40dc48bd49c4adbffb825b31f96 diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 index 468ed6940..f773e61f8 100644 --- a/doc/man/lttng.1 +++ b/doc/man/lttng.1 @@ -1,7 +1,7 @@ -.TH "LTTNG" "1" "July 17, 2012" "" "" +.TH "LTTNG" "1" "December 3rd, 2012" "" "" .SH "NAME" -lttng \(em LTTng 2.0 tracer control command line tool +lttng \(em LTTng 2.1.x tracer control command line tool .SH "SYNOPSIS" @@ -23,11 +23,18 @@ be done by this tool or by the liblttng-ctl provided with the lttng-tools package. LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry, -which permits you to interact with multiple tracers (kernel and user-space) +which allows you to interact with multiple tracers (kernel and user-space) inside the same container, a tracing session. Traces can be gathered from the kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading those traces is done using the babeltrace(1) text viewer. +We introduce the notion of \fBtracing domains\fP which is essentially a type of +tracer (kernel or user space for now). In the future, we could see a third +tracer being for instance an hypervisor. For some commands, you'll need to +specify on which domain the command applies (-u or -k). For instance, enabling +a kernel event, you must specify the kernel domain to the command so we know +for which tracer this event is for. + 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 @@ -65,7 +72,7 @@ Set unix tracing group name. (default: tracing) .BR "\-n, \-\-no-sessiond" Don't automatically spawn a session daemon. .TP -.BR "\-\-sessiond\-path" +.BR "\-\-sessiond\-path PATH" Set session daemon full binary path. .TP .BR "\-\-list\-options" @@ -80,10 +87,10 @@ Simple listing of lttng commands. .nf Add context to event(s) and/or channel(s). -A context is basically extra information appended to a channel or event. For -instance, you could ask the tracer to add the PID information within the -"sched_switch" kernel event. You can also add performance monitoring unit -counters (perf PMU) using the perf kernel API). +A context is basically extra information appended to a channel. For instance, +you could ask the tracer to add the PID information for all events in a +channel. You can also add performance monitoring unit counters (perf PMU) using +the perf kernel API). For example, this command will add the context information 'prio' and two perf counters (hardware branch misses and cache misses), to all events in the trace @@ -94,9 +101,8 @@ data output: Please take a look at the help (\-h/\-\-help) for a detailed list of available contexts. -If no channel and no event is given (\-c/\-e), the context is added to all -channels (which applies automatically to all events in that channel). Otherwise -the context will be added only to the channel (\-c) and/or event (\-e) indicated. +If no channel is given (\-c), the context is added to all channels. Otherwise +the context will be added only to the given channel (\-c). If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc file. @@ -111,8 +117,6 @@ file. Apply on session name. \-c, \-\-channel NAME Apply on channel name. -\-e, \-\-event NAME - Apply on event name. \-k, \-\-kernel Apply for the kernel tracer \-u, \-\-userspace @@ -294,7 +298,7 @@ file. Show this help \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME Apply on session name \-k, \-\-kernel Apply to the kernel tracer @@ -305,16 +309,18 @@ file. Discard event when subbuffers are full (default) \-\-overwrite Flight recorder mode : overwrites events when subbuffers are full -\-\-subbuf-size +\-\-subbuf-size SIZE Subbuffer size in bytes (default: 4096, kernel default: 262144) -\-\-num-subbuf +\-\-num-subbuf NUM Number of subbuffers (default: 4) Needs to be a power of 2 for kernel and ust tracers -\-\-switch-timer +\-\-switch-timer USEC Switch subbuffer timer interval in usec (default: 0) Needs to be a power of 2 for kernel and ust tracers -\-\-read-timer +\-\-read-timer USEC Read timer interval in usec (default: 200) +\-\-output TYPE + Channel output type. Possible values: mmap, splice .fi .IP @@ -344,7 +350,7 @@ that can understand the streaming protocol of LTTng. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME Apply on session name \-k, \-\-kernel Apply for the kernel tracer @@ -374,10 +380,10 @@ Supported protocols are (proto): > file://... Local filesystem full path. -> net[6]://... +> net://... This will use the default network transport layer which is TCP for both control (PORT1) and data port (PORT2). The default ports are - respectively 5342 and 5343. + respectively 5342 and 5343. Note that net[6]:// is not yet supported. > tcp[6]://... Can only be used with -C and -D together @@ -413,12 +419,13 @@ file. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-s, \-\-session NAME Apply on session name -\-c, \-\-channel +\-c, \-\-channel NAME Apply on channel name \-a, \-\-all - Enable all tracepoints and syscalls + Enable all tracepoints and syscalls. This actually enable a single + wildcard event "*". \-k, \-\-kernel Apply for the kernel tracer \-u, \-\-userspace @@ -431,8 +438,13 @@ file. e.g.: "*" "app_component:na*" -\-\-loglevel - Tracepoint loglevel +\-\-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...) @@ -531,8 +543,11 @@ file. Show summary of possible options and commands. \-\-list-options Simple listing of options -\-s, \-\-session +\-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 @@ -624,7 +639,10 @@ If NAME is omitted, the session name is taken from the .lttngrc file. .nf Stop tracing -It will stop tracing for all tracers for a specific tracing session. +It will stop tracing for all tracers for a specific tracing session. Before +returning, the command checks for data availability meaning that it will wait +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 @@ -636,6 +654,8 @@ If NAME is omitted, the session name is taken from the .lttngrc file. Show summary of possible options and commands. \-\-list-options Simple listing of options +\-\-no-wait + Don't wait for data availability. .fi .IP @@ -712,10 +732,6 @@ tool. You can also use \-\-sessiond-path option having the same effect. .BR lttng-health-check(3) .SH "BUGS" -With version 2.1 and earlier, if you start a tracing session and than enable -kernel events, they are not recorded and the tracing session fails to stop. To -fix this, simply enable events before starting the session. - 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.