.TH "LTTNG" "1" "May 13th, 2014" "" ""
.SH "NAME"
-lttng \(em LTTng 2.x tracer control command line tool
+lttng \- LTTng 2.x tracer control command line tool
.SH "SYNOPSIS"
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, user space or JUL for now). In the future, we could see more
-tracer like for instance an hypervisor. For some commands, you'll need to
-specify on which domain the command operates (\-u, \-k or \-j). For instance,
-the kernel domain must be specified when enabling a kernel event.
+tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
+could see more tracer like for instance an hypervisor. For some commands,
+you'll need to specify on which domain the command operates (\-u, \-k, \-l, \-j
+or \-p). 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
.SH "OPTIONS"
.PP
-This program follow the usual GNU command line syntax with long options starting with
+This program follows the usual GNU command line syntax with long options starting with
two dashes. Below is a summary of the available options.
.PP
.BR "\-h, \-\-help"
Show summary of possible options and commands.
.TP
+.BR "\-V, \-\-version"
+Show version.
+.TP
.BR "\-v, \-\-verbose"
Increase verbosity.
Three levels of verbosity are available which are triggered by putting additional v to
in overwrite mode and with mmap output (splice not supported).
.TP
.BR "\-\-live [USEC]"
-Set the session exclusively in live mode. The paremeter is the delay in micro
+Set the session exclusively in live mode. The parameter is the delay in micro
seconds before the data is flushed and streamed. The live mode allows you to
stream the trace and view it while it's being recorded by any tracer. For that,
you need a lttng-relayd and this session requires a network URL (\-U or
After the start, you'll be able to read the events while they are being
recorded in /tmp/lttng.
+.TP
+.BR "\-\-shm-path PATH"
+
+Path where shared memory holding buffers should be created. Useful
+when used with PRAMFS or other persistent memory filesystems to extract
+trace data in the event of a crash requiring a reboot.
+
+See the \fBlttng-crash(1)\fP utility for more information on crash recovery.
+
.TP
.BR "\-U, \-\-set-url=URL"
Set URL for the consumer output destination. It is persistent for the
.PP
.PP
-\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]
+\fBenable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [OPTIONS]
.RS
Enable tracing event
.BR "\-j, \-\-jul"
Apply for Java application using Java Util Logging interface (JUL)
.TP
+.BR "\-l, \-\-log4j"
+Apply for Java application using LOG4J
+.TP
+.BR "\-p, \-\-python"
+Apply for Python application using the logging module.
+.TP
.BR "\-\-tracepoint"
Tracepoint event (default). Userspace tracer supports wildcards at the end
of string. Don't forget to quote to deal with bash expansion.
Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
For the JUL domain, the loglevel ranges are detailed with the \-\-help
option thus starting from SEVERE to FINEST.
+For the LOG4J domain, loglevels range from FATAL to TRACE which are also
+detailed in the help.
+For the Python domain, loglevels range from CRITICAL to DEBUG which are
+detailed in the help as well.
.TP
.BR "\-\-loglevel-only NAME"
Tracepoint loglevel (only this loglevel).
(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. Also note
-that per-syscall selection is not supported yet. Use with "-a" to enable
-all syscalls.
+System call event.
.TP
.BR "\-\-filter 'expression'"
Set a filter on a newly enabled event. Filter expression on event
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.
-Filtering is currently only implemented for the user-space tracer.
Expression examples:
'intfield > 500 && intfield < 503'
'(strfield == "test" || intfield != 10) && intfield > 33'
'doublefield > 1.1 && intfield < 5.3'
+ 'enumfield == 1234'
.fi
Wildcards are allowed at the end of strings:
In string literals, the escape character is a '\\'. Use '\\*' for
the '*' character, and '\\\\' for the '\\' character sequence. Wildcard
matches any sequence of characters, including an empty sub-string
-(matches 0 or more characters).
+(matches 0 or more characters). Enumeration fields can currently only be
+compared as integers.
Context information can be used for filtering. The examples below shows
usage of context filtering on the process name (using a wildcard), process ID
.PP
.PP
-\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
+\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [TYPE] [OPTIONS]
.RS
Disable tracing event
Apply on channel name
.TP
.BR "\-a, \-\-all-events"
-Disable all events. This does NOT disable "*" but rather every known
-events of the session.
+Disable all events. This does NOT ONLY disable "*" but rather every known
+events of the session
.TP
.BR "\-k, \-\-kernel"
Apply for the kernel tracer
.TP
.BR "\-j, \-\-jul"
Apply for Java application using Java Util Logging interface (JUL)
+.TP
+.BR "\-l, \-\-log4j"
+Apply for Java application using LOG4J
+.TP
+.BR "\-p, \-\-python"
+Apply for Python application using the logging module
+
+.TP
+.B TYPE (kernel domain only):
+
+.TP
+.BR "\-\-all"
+Disable event of all type
+.TP
+.BR "\-\-tracepoint"
+Disable event of type tracepoint
+.TP
+.BR "\-\-syscall"
+Disable event of type syscall
+.TP
+.BR "\-\-probe"
+Disable event of type probe
+.TP
+.BR "\-\-function"
+Disable event of type function
.RE
.PP
calls events).
With \-j alone, the available JUL event from registered application will be
list. The event corresponds to the Logger name in the Java JUL application.
+With \-l alone, the available LOG4J event from registered application will be
+list. The event corresponds to the Logger name in the Java LOG4J application.
+With \-p alone, the available Python event from registered application will be
+list. The event corresponds to the Logger name in the Python application.
With \-u alone, it will list all available user-space events from registered
applications. Here is an example of 'lttng list \-u':
.BR "\-j, \-\-jul"
Apply for Java application using JUL
.TP
+.BR "\-l, \-\-log4j"
+Apply for Java application using LOG4J
+.TP
+.BR "\-p, \-\-python"
+Apply for Python application using the logging module.
+.TP
.BR "\-f, \-\-fields"
List event fields
.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
+Setup and add a snapshot output for a session. Output is 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.
+Delete an output for a session using the output's ID. You can either specify the
+output by name or use its ID as returned by the list-output command.
.TP
\fBlist-output\fP [-s <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
+Maximum size in bytes of the snapshot. The maximum size does not include the
metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
\-\-max-size 5M
-
-The minimum size of a snapshot is computed by multiplying the total amount of
-streams in the session by the largest subbuffer size. This is to ensure
-fairness between channels when extracting data.
.TP
.BR "\-C, \-\-ctrl-url URL"
Set control path URL. (Must use -D also)
.RE
.PP
+.PP
+\fBtrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
+.RS
+Adds one or more entries to a tracker
+
+The \fBtrack\fP command adds one or more entries to a tracker. A tracker is
+a whitelist of resources. Tracked resources are allowed to emit events, provided
+those events are enabled (see the \fBenable-event\fP command).
+
+Tracker entries can be removed from the whitelist with the
+\fBuntrack\fP command.
+
+As of this version, the only available tracker is the \fBPID tracker\fP. The
+process ID (PID) tracker follows one or more process IDs;
+only the processes with a tracked PID are allowed to emit events. By default,
+all possible PIDs on the system are tracked: any process may emit enabled
+events (equivalent of \fBlttng track \-\-pid \-\-all\fR for all domains).
+
+With the PID tracker, it is possible, for example, to record all system calls
+called by a given process:
+
+.nf
+ $ lttng enable-event --kernel --all --syscall
+ $ lttng track --kernel --pid 2345
+ $ lttng start
+.fi
+
+If all the PIDs are tracked (i.e. \fBlttng track \-\-pid \-\-all\fR, which
+is the default state of all domains when creating a tracing session), then
+using the \fBtrack\fR command with one or more specific PIDs has the effect of
+first removing all the PIDs from the whitelist, then adding the specified PIDs.
+
+Assume the maximum PID is 7 for the following examples:
+
+.nf
+ Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
+
+ $ lttng track --userspace --pid 3,6,7
+
+ Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
+
+ $ lttng untrack --userspace --pid 7
+
+ Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
+
+ $ lttng track --userspace --pid 1,5
+
+ Whitelist: [ ] [1] [ ] [3] [ ] [5] [6] [ ]
+.fi
+
+It should be noted that the PID tracker tracks the numeric process IDs.
+Should a process with a given ID exit and another process be given this
+ID, then the latter would also be allowed to emit events.
+
+See the \fBuntrack\fR command's documentation for more details about
+removing entries.
+
+.B OPTIONS:
+
+.TP
+.BR "\-s, \-\-session NAME"
+Apply to session name.
+.TP
+.BR "\-k, \-\-kernel"
+Apply to the kernel tracer.
+.TP
+.BR "\-u, \-\-userspace"
+Apply to the user space tracer.
+.TP
+.BR "\-p, \-\-pid [PIDS]"
+Track process IDs PIDS (add to whitelist).
+
+PIDS is a comma-separated list of PIDs to add to the PID tracker.
+
+The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
+.TP
+.BR "\-a, \-\-all"
+Used in conjunction with an empty \fB\-\-pid\fP option: track all process IDs
+(add all entries to whitelist).
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.RE
+.PP
+
+.PP
+\fBuntrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
+.RS
+Removes one or more entries from a tracker
+
+See the \fBtrack\fP command's documentation to learn more about LTTng
+trackers.
+
+The \fBuntrack\fP command removes specific resources from a tracker. The
+resources to remove must have been precedently added by the
+\fBtrack\fP command. It is also possible to remove all the resources
+from the whitelist using the \fB\-\-all\fR option.
+
+As of this version, the only available tracker is the \fBPID tracker\fP.
+
+One common operation is to create a tracing session, remove all the entries
+from the PID tracker whitelist, start tracing, and then manually track PIDs
+while tracing is active.
+
+Assume the maximum PID is 7 for the following examples:
+
+.nf
+ $ lttng create
+
+ Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
+
+ $ lttng untrack --userspace --pid --all
+
+ Whitelist: [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
+
+ $ lttng enable-event --userspace ...
+ $ lttng start
+ ...
+ $ lttng track --userspace --pid 3,5
+
+ Whitelist: [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
+
+ $ lttng track --userspace --pid 2
+
+ Whitelist: [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
+.fi
+
+See the \fBtrack\fR command's documentation for more details about
+adding entries.
+
+.B OPTIONS:
+
+.TP
+.BR "\-s, \-\-session NAME"
+Apply to session name.
+.TP
+.BR "\-k, \-\-kernel"
+Apply to the kernel tracer.
+.TP
+.BR "\-u, \-\-userspace"
+Apply to the user space tracer.
+.TP
+.BR "\-p, \-\-pid [PIDS]"
+Stop tracking process IDs PIDS (remove from whitelist).
+
+PIDS is a comma-separated list of PIDs to remove from the PID tracker.
+
+The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
+.TP
+.BR "\-a, \-\-all"
+Used in conjunction with an empty \fB\-\-pid\fP option: stop tracking all
+process IDs (remove all entries from whitelist).
+.TP
+.BR "\-h, \-\-help"
+Show summary of possible options and commands.
+.TP
+.BR "\-\-list-options"
+Simple listing of options
+.RE
+.PP
+
.PP
\fBversion\fP
.RS
.RE
.PP
-.SH "JUL DOMAIN"
-This section explains the JUL domain (\-j, \-\-jul) where JUL stands for Java
-Util Logging. You can use that feature by using the \fBliblttng-ust-jul.so\fP
-from the lttng-ust(3) project.
+.SH "JUL/LOG4J DOMAIN"
+
+This section explains the JUL and LOG4J domain where JUL stands for Java Util
+Logging. You can use these by using the \fBliblttng-ust-<domain>-jni.so\fP from
+the lttng-ust(3) project.
The LTTng Java Agent uses JNI to link the UST tracer to the Java application
that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
-enabling events with the JUL domain, you enable a Logger name that will then be
-mapped to a default UST tracepoint called \fBlttng_jul:jul_event\fP in the
-\fBlttng_jul_channel\fP. Using the lttng-ctl API, any JUL events must use the
-tracepoint event type (same as \-\-tracepoint).
+enabling events, you enable a Logger name that will then be mapped to a default
+UST tracepoint called \fBlttng_jul:<domain>_event\fP in the
+\fBlttng_<domain>_channel\fP. Using the lttng-ctl API, any JUL/LOG4J events
+must use the tracepoint event type (same as \-\-tracepoint).
-Because of the default immutable channel (\fBlttng_jul_channel\fP), the
-\fBenable-channel\fP command CAN NOT be used with the JUL domain thus not
-having any \-j option.
+Because of the default immutable channel, the \fBenable-channel\fP command CAN
+NOT be used with the JUL and LOG4J domain thus not having any options.
-For JUL event, loglevels are supported with the JUL ABI values. Use \fBlttng
-enable-event \-h\fP to list them. Wildcards are NOT supported except the "*"
-meaning all events (same as \-a).
+Also, loglevels are supported. Use \fBlttng enable-event \-h\fP to list them.
+Wildcards are NOT supported except the "*" meaning all events (same as \-a).
Exactly like the UST domain, if the Java application has the same UID as you,
you can trace it. Same goes for the tracing group accessing root applications.
-Finally, you can list every Logger name that are available from JUL registered
-applications to the session daemon by using \fBlttng list \-j\fP.
+Finally, you can list every Logger name that are available from registered
+applications to the session daemon by using \fBlttng list \-j\fP or \fB\-l\fP.
-Here is an example on how to use this domain.
+Here is an example on how to use the JUL domain.
.nf
$ lttng list -j
.BR lttng-ust(3),
.BR lttng-sessiond(8),
.BR lttng-relayd(8),
+.BR lttng-crash(1),
.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.
+at https://bugs.lttng.org which is a bug tracker.
.PP
.SH "CREDITS"
.PP
lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
David Goulet. More people have since contributed to it. It is currently
-maintained by David Goulet <dgoulet@efficios.com>.
+maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
.PP
projects / lttng-tools.git / blobdiff