-.TH "LTTNG" "1" "December 3rd, 2012" "" ""
+.TH "LTTNG" "1" "July 18th, 2013" "" ""
.SH "NAME"
lttng \(em LTTng 2.x tracer control command line tool
.SH "SYNOPSIS"
.PP
-.nf
lttng [OPTIONS] <COMMAND>
-.fi
.SH "DESCRIPTION"
.PP
If no channel is given (\-c), the context is added to all channels that were
already enabled. If the session has no channel, a default channel is created.
-Otherwise the context will be added only to the given channel (\-c).
+If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
+exists within the session, an error is returned. 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.
.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
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.
-.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:
+
+.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.
-.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
.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
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
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).
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 <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
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 <NAME>]
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 <NAME>]
List the output of a session. Attributes of the output are printed.
+.TP
\fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
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
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 <lttng/lttng-error.h>
+.BR "<lttng/lttng-error.h>"
for a detailed list or use lttng_strerror() to get a human readable string of
the error code.
-
.PP
+
.SH "ENVIRONMENT VARIABLES"
.PP
.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 <lttng-dev@lists.lttng.org> to help improve this project or
at https://bugs.lttng.org which is a bugtracker.
+.PP
+
.SH "CREDITS"
.PP