-.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
.PP
.PP
-.IP \fBcreate\fP [NAME] [OPTIONS]
+\fBcreate\fP [NAME] [OPTIONS]
.RS
Create tracing session.
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
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.
.RE
.PP
-.IP "\fBdisable-channel\fP NAME[,NAME2,...] [\-k|\-u] [OPTIONS]"
-.nf
+.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. 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
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
projects / lttng-tools.git / blobdiff