lttng-track — Add one or more entries to an LTTng resource tracker
lttng [GENERAL OPTIONS] track (--kernel
|--userspace
) [--session
=SESSION
] (--pid
=PID
[,PID
]… |--all
--pid
)
The lttng track
commands adds one or more entries to a
resource tracker.
A resource tracker is a whitelist of resources. Tracked resources are allowed to emit events, provided those events are targeted by enabled event rules (see lttng-enable-event(1)).
Tracker entries can be removed from the whitelist with lttng-untrack(1).
As of this version, the only available tracker is the PID tracker. 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 lttng track --pid --all
for all domains).
With the PID tracker, it is possible, for example, to record all system calls called by a given process:
lttng enable-event --kernel --all --syscall lttng track --kernel --pid=2345 lttng start
If all the PIDs are tracked (i.e. lttng track --pid --all
, which is
the default state of all domains when creating a tracing session), then
using the track 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 system PID is 7 for this example.
Initial whitelist:
[0] [1] [2] [3] [4] [5] [6] [7]
Command:
lttng track --userspace --pid=3,6,7
Whitelist:
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
Command:
lttng untrack --userspace --pid=7
Whitelist:
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
Command:
lttng track --userspace --pid=1,5
Whitelist:
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
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 lttng-untrack(1) for more details about removing entries.
General options are described in lttng(1).
One of:
-k
, --kernel
Track resources in the Linux kernel domain.
-u
, --userspace
Track resources in the user space domain.
-h
, --help
Show command help.
This option, like lttng-help(1), attempts to launch
/usr/bin/man
to view the command’s man page. The path to the man pager
can be overridden by the LTTNG_MAN_BIN_PATH
environment variable.
--list-options
List available command options.
LTTNG_ABORT_ON_ERROR
Set to 1 to abort the process after the first error is encountered.
LTTNG_HOME
Overrides the $HOME
environment variable. Useful when the user
running the commands has a non-writable home directory.
LTTNG_MAN_BIN_PATH
Absolute path to the man pager to use for viewing help information
about LTTng commands (using lttng-help(1) or
lttng COMMAND --help
).
LTTNG_SESSION_CONFIG_XSD_PATH
Path in which the session.xsd
session configuration XML
schema may be found.
LTTNG_SESSIOND_PATH
Full session daemon binary path.
The --sessiond-path
option has precedence over this
environment variable.
Note that the lttng-create(1) command can spawn an LTTng session daemon automatically if none is running. See lttng-sessiond(8) for the environment variables influencing the execution of the session daemon.
$LTTNG_HOME/.lttngrc
User LTTng runtime configuration.
This is where the per-user current tracing session is stored between executions of lttng(1). The current tracing session can be set with lttng-set-session(1). See lttng-create(1) for more information about tracing sessions.
$LTTNG_HOME/lttng-traces
Default output directory of LTTng traces. This can be overridden
with the --output
option of the lttng-create(1)
command.
$LTTNG_HOME/.lttng
User LTTng runtime and configuration directory.
$LTTNG_HOME/.lttng/sessions
Default location of saved user tracing sessions (see lttng-save(1) and lttng-load(1)).
/etc/lttng/sessions
System-wide location of saved tracing sessions (see lttng-save(1) and lttng-load(1)).
Note:$LTTNG_HOME
defaults to $HOME
when not explicitly set.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
If you encounter any issue or usability problem, please report it on the LTTng bug tracker.
Mailing list for support and
development: lttng-dev@lists.lttng.org
IRC channel: #lttng
on irc.oftc.net
This program is part of the LTTng-tools project.
LTTng-tools is distributed under the
GNU General
Public License version 2. See the
LICENSE
file
for details.
Special thanks to Michel Dagenais and the DORSAL laboratory at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.