.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"
.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
.BR "\-\-shm-path PATH"
Path where shared memory holding buffers should be created. Useful
-when used with pramfs to extract trace data after crash.
+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"
.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
(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
Apply for Java application using LOG4J
.TP
.BR "\-p, \-\-python"
-Apply for Python application using the logging module.
+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
.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
.BR lttng-ust(3),
.BR lttng-sessiond(8),
.BR lttng-relayd(8),
+.BR lttng-crash(1),
.SH "BUGS"
projects / lttng-tools.git / blobdiff