lttng-track — Add one or more values to an LTTng process attribute tracker
Add specific process attribute values to a Linux kernel domain tracker:
lttng [GENERAL OPTIONS] track--kernel
(--pid
=PID[,PID]… |--vpid
=VPID[,VPID]… |--uid
=UID[,UID]… |--vuid
=VUID[,VUID]… |--gid
=GID[,GID]… |--vgid
=VGID[,VGID]… )…
Add all possible process attribute values to a Linux kernel domain tracker:
lttng [GENERAL OPTIONS] track--kernel
--all
(--pid
|--vpid
|--uid
|--vuid
|--gid
|--vgid
)…
Add specific process attribute values to a user space domain tracker:
lttng [GENERAL OPTIONS] track--userspace
(--vpid
=VPID[,VPID]… |--vuid
=VUID[,VUID]… |--vgid
=VGID[,VGID]…)…
Add all possible process attribute values to a user space domain tracker:
lttng [GENERAL OPTIONS] track--userspace
--all
(--vpid
|--vgid
|--vuid
)…
The lttng track
commands adds one or more values to a
process attribute tracker.
A process attribute tracker is an inclusion set of process attributes. Tracked processes are allowed to emit events, provided those events are targeted by enabled event rules (see lttng-enable-event(1)).
Tracker values can be removed from an inclusion set with lttng-untrack(1).
The available process attribute trackers are:
Process ID (PID)
Virtual PID (VPID)
User ID (UID)
Virtual UID (VUID)
Group ID (GID)
Virtual GID (VGID)
A tracker follows one or more process attribute values; only the processes with a tracked value are allowed to emit events. By default, all possible values on the system are tracked: any process may emit enabled events, the equivalent of:
$ $
lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all lttng track --userspace --vpid --vuid --vgid --all
With the PID tracker, for example, you can record all system calls of a given process:
$ $ $
lttng enable-event --kernel --all --syscall lttng track --kernel --pid=2345 lttng start
If all the PIDs are tracked (with the --pid
and --all
options), 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
inclusion set, then adding the specified PIDs.
Assume the maximum system PID is 7 for this example.
Initial inclusion set:
[0] [1] [2] [3] [4] [5] [6] [7]
Command:
$
lttng track --kernel --pid=3,6,7
inclusion set:
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
Command:
$
lttng untrack --kernel --pid=7
inclusion set:
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
Command:
$
lttng track --kernel --pid=1,5
inclusion set:
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
See the lttng-untrack(1) for more details about removing values from the inclusion set.
General options are described in lttng(1).
One of:
-k
, --kernel
Track process attributes in the Linux kernel domain.
-u
, --userspace
Track process attributes in the user space domain.
-a
, --all
Used in conjunction with a single, empty --pid
,
--vpid
, --uid
, --vuid
, --gid
,
or --vgid
option: track all possible process attribute
values (add all values to the inclusion set).
-p
[PID
[,PID
]…], --pid
[=PID
[,PID
]…]
Track process ID values PID
(add them to the process ID inclusion
set).
PID
is the process ID attribute of a process as seen from the root
PID namespace (see pid_namespaces(7)). It can only be used with
the --kernel
domain option.
The PID
argument must be omitted when also using the --all
option.
--vpid
[=VPID
[,VPID
]…]
Track virtual process ID values VPID
(add them to the virtual
process ID inclusion set).
VPID
is the virtual process ID attribute of a process as seen from
the PID namespace of the process (see pid_namespaces(7)).
The VPID
argument must be omitted when also using the --all
option.
--uid
[=USER
[,USER
]…]
Track user ID process attribute values USER
(add them to the
user ID inclusion set).
USER
is the real user ID (see getuid(3)) of a process as seen
from the root user namespace (see user_namespaces(7)). It can
only be used with the --kernel
domain option.
USER
can also be a user name. The user name resolution is performed
by the session daemon (see lttng-sessiond(8)) on addition to the
user ID inclusion set.
The USER
argument must be omitted when also using the --all
option.
--vuid
[=USER
[,USER
]…]
Track virtual user ID process attribute values USER
(add them to
the virtual user ID inclusion set).
USER
is the real user ID (see getuid(3)) of a process as seen
from the user namespace of the process (see user_namespaces(7)).
USER
can also be a user name. The user name resolution is performed
by the session daemon (see lttng-sessiond(8)) on addition to the
virtual user ID inclusion set.
The USER
argument must be omitted when also using the --all
option.
--gid
[=GROUP
[,GROUP
]…]
Track group ID process attribute values GROUP
(add them to the
group ID inclusion set).
GROUP
is the real group ID (see getgid(3)) of a process as seen
from the root user namespace (see user_namespaces(7)). It can
only be used with the --kernel
domain option.
GROUP
can also be a group name. The group name resolution is
performed by the session daemon (see lttng-sessiond(8)) on addition
to the group ID inclusion set.
The GROUP
argument must be omitted when also using the --all
option.
--vgid
[=GROUP
[,GROUP
]…]
Track virtual group ID process attribute values GROUP
(add them to
the virtual group ID inclusion set).
GROUP
is the real group ID (see getgid(3)) of a process as seen
from the user namespace of the process (see user_namespaces(7)).
GROUP
can also be a group name. The group name resolution is performed
by the session daemon (see lttng-sessiond(8)) on addition to the
virtual group ID inclusion set.
The GROUP
argument must be omitted when also using the --all
option.
-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.