.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
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
(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
.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>]
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
.BR lttng-ust(3),
.BR lttng-sessiond(8),
.BR lttng-relayd(8),
+.BR lttng-crash(1),
.SH "BUGS"
projects / lttng-tools.git / blobdiff