projects
/
lttng-tools.git
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
Fix: Some corrections to the lttng man page
[lttng-tools.git]
/
doc
/
man
/
lttng.1
diff --git
a/doc/man/lttng.1
b/doc/man/lttng.1
index 236603fa087eaa3dbe5432f867653f7c2acef816..0f9cd9c516b3a3fbc4955643ab1e6e4885babc61 100644
(file)
--- a/
doc/man/lttng.1
+++ b/
doc/man/lttng.1
@@
-11,13
+11,13
@@
lttng [OPTIONS] <COMMAND>
.PP
The LTTng project aims at providing highly efficient tracing tools for Linux.
.PP
The LTTng project aims at providing highly efficient tracing tools for Linux.
-It
's tracers help tracking down performance issues and debuggin
g problems
+It
s tracers help track down performance issues and debu
g problems
involving multiple concurrent processes and threads. Tracing across multiple
systems is also possible.
The \fBlttng\fP command line tool from the lttng-tools package is used to control
involving multiple concurrent processes and threads. Tracing across multiple
systems is also possible.
The \fBlttng\fP command line tool from the lttng-tools package is used to control
-both kernel and user-space tracing. Every interaction
s
with the tracer should
-be done by this tool or by the liblttng-ctl
provided with
the lttng-tools
+both kernel and user-space tracing. Every interaction with the tracer should
+be done by this tool or by the liblttng-ctl
library provided by
the lttng-tools
package.
LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
package.
LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
@@
-29,19
+29,18
@@
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
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.
+specify on which domain the command operates (-u or -k). For instance, the
+kernel domain must be specified when enabling a kernel event.
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
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
+kernel. Session daemons can co-exist
,
meaning that you can have a session daemon
running as Alice that can be used to trace her applications along side with a
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
+root daemon or even a Bob daemon. We highly recommend
starting
the session
daemon at boot time for stable and long term tracing.
daemon at boot time for stable and long term tracing.
-
Every user-space applications instrumented with lttng-ust(3),
will
+
All user-space applications instrumented with lttng-ust(3)
will
automatically register to the session daemon. This feature gives you the
ability to list available traceable applications and tracepoints on a per user
basis. (See \fBlist\fP command).
automatically register to the session daemon. This feature gives you the
ability to list available traceable applications and tracepoints on a per user
basis. (See \fBlist\fP command).
@@
-214,12
+213,12
@@
Dynamic function entry/return probe (default)
.PP
.PP
.PP
.PP
-
.IP
\fBcreate\fP [NAME] [OPTIONS]
+\fBcreate\fP [NAME] [OPTIONS]
.RS
Create tracing session.
A tracing session contains channel(s) which contains event(s). It is domain
.RS
Create tracing session.
A tracing session contains channel(s) which contains event(s). It is domain
-agnostic
meaning that you can enable channels and events for eithe
r the
+agnostic
, meaning that channels and events can be enabled fo
r the
user-space tracer and/or the kernel tracer. It acts like a container
aggregating multiple tracing sources.
user-space tracer and/or the kernel tracer. It acts like a container
aggregating multiple tracing sources.
@@
-247,11
+246,11
@@
Simple listing of options
Specify output path for traces
.TP
.BR "\-\-no-output"
Specify output path for traces
.TP
.BR "\-\-no-output"
-Traces will not be output
ed
+Traces will not be output
.TP
.BR "\-\-snapshot"
Set the session in snapshot mode. Created in no-output mode and uses the
.TP
.BR "\-\-snapshot"
Set the session in snapshot mode. Created in no-output mode and uses the
-URL, if one, as the default snapshot output. Every channel will be set
+URL, if one
is specified
, as the default snapshot output. Every channel will be set
in overwrite mode and with mmap output (splice not supported).
.TP
in overwrite mode and with mmap output (splice not supported).
.TP
@@
-425,7
+424,7
@@
created to the specified count. 0 means unlimited. (default: 0)
.nf
$ lttng enable-channel -k -C 4096 -W 32 chan1
.fi
.nf
$ lttng enable-channel -k -C 4096 -W 32 chan1
.fi
-For each stream, the maximum size of each trace file will be 4096 bytes
,
and
+For each stream, the maximum size of each trace file will be 4096 bytes and
there will be a maximum of 32 different files. The file count is appended after
the stream number as seen in the following example. The last trace file is
smaller than 4096 since it was not completely filled.
there will be a maximum of 32 different files. The file count is appended after
the stream number as seen in the following example. The last trace file is
smaller than 4096 since it was not completely filled.
@@
-453,8
+452,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
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.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
@@
-475,7
+476,7
@@
Apply on session name
Apply on channel name
.TP
.BR "\-a, \-\-all"
Apply on channel name
.TP
.BR "\-a, \-\-all"
-Enable all tracepoints and syscalls. This actually enable a single
+Enable all tracepoints and syscalls. This actually enable
s
a single
wildcard event "*".
.TP
.BR "\-k, \-\-kernel"
wildcard event "*".
.TP
.BR "\-k, \-\-kernel"
@@
-485,7
+486,7
@@
Apply for the kernel tracer
Apply for the user-space tracer
.TP
.BR "\-\-tracepoint"
Apply for the user-space tracer
.TP
.BR "\-\-tracepoint"
-Tracepoint event (default). Userspace tracer supports wildcards at end
+Tracepoint event (default). Userspace tracer supports wildcards at
the
end
of string. Don't forget to quote to deal with bash expansion.
e.g.:
.nf
of string. Don't forget to quote to deal with bash expansion.
e.g.:
.nf
@@
-516,12
+517,13
@@
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
.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
+fields and context. The event will be recorded if the filter's
+expression evaluates to TRUE. Only specify on first activation of a
+given event within a session.
+Specifying a filter is 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.
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.
+
Filtering is currently
only implemented for the user-space tracer.
Expression examples:
Expression examples:
@@
-534,13
+536,13
@@
Expression examples:
Wildcards are allowed at the end of strings:
'seqfield1 == "te*"'
In string literals, the escape character is a '\\'. Use '\\*' for
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).
+the '*' character, and '\\\\' for the '\\' character
sequence
. Wildcard
+match
es
any sequence of characters, including an empty sub-string
+(match
es
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
+Context information can be used for filtering. The examples below show
s
+usage of context filtering on
the process name (using
a wildcard), process ID
+range, and unique thread ID
. The process and thread IDs
of
running applications can be found under columns "PID" and "LWP" of the
"ps -eLf" command.
running applications can be found under columns "PID" and "LWP" of the
"ps -eLf" command.
@@
-558,8
+560,8
@@
running applications can be found under columns "PID" and "LWP" of the
.RS
Disable tracing channel
.RS
Disable tracing channel
-Disabling a channel
makes all event(s) in that channel to stop tracing. You can
-
enable it back
by calling \fBlttng enable-channel NAME\fP again.
+Disabling a channel
disables the tracing of all of the channel's events. A channel
+
can be reenabled
by calling \fBlttng enable-channel NAME\fP again.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
@@
-595,6
+597,10
@@
NAME\fP again.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
file.
+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:
.TP
.B OPTIONS:
.TP
@@
-607,6
+613,9
@@
Simple listing of options
.BR "\-s, \-\-session NAME"
Apply on session name
.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.
.BR "\-a, \-\-all-events"
Disable all events. This does NOT disable "*" but rather every known
events of the session.
@@
-733,7
+742,7
@@
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
snapshot with a custom maximum size or with a different name.
.nf
-$ lttng add-output -n mysnapshot file:///data/snapshot
+$ lttng
snapshot
add-output -n mysnapshot file:///data/snapshot
[...]
$ lttng snapshot record -n new_name_snapshot
.fi
[...]
$ lttng snapshot record -n new_name_snapshot
.fi
@@
-752,8
+761,9
@@
Apply to session name.
Name of the snapshot's output.
.TP
.BR "\-m, \-\-max-size SIZE"
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.
+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 "\-C, \-\-ctrl-url URL"
Set control path URL. (Must use -D also)
This page took
0.026309 seconds
and
4
git commands to generate.