See the --pid
option.
$
lttng track --kernel --pid=1728,3775
lttng-track — Allow specific processes to record LTTng events
Allow specific processes to record Linux kernel events:
lttng [GENERAL OPTIONS] track--kernel
[--session
=SESSION
] (--pid
=PID[,PID]… |--vpid
=VPID[,VPID]… |--uid
=UID[,UID]… |--vuid
=VUSER[,VUSER]… |--gid
=GID[,GID]… |--vgid
=VGROUP[,VGROUP]…)…
lttng [GENERAL OPTIONS] track--kernel
[--session
=SESSION
]--all
(--pid
|--vpid
|--uid
|--vuid
|--gid
|--vgid
)…
Allow specific processes to record user space events:
lttng [GENERAL OPTIONS] track--userspace
[--session
=SESSION
] (--vpid
=VPID[,VPID]… |--vuid
=VUSER[,VUSER]… |--vgid
=VGROUP[,VGROUP]…)…
lttng [GENERAL OPTIONS] track--userspace
[--session
=SESSION
]--all
(--vpid
|--vgid
|--vuid
)…
The lttng track
command allows one or more processes to record LTTng
events based on their attributes within:
--session
=SESSION
option
The recording session named SESSION
.
--session
option
The current recording session (see lttng-concepts(7) to learn more about the current recording session).
See lttng-concepts(7) to learn more about recording sessions and recording event rules.
The track
command adds values to inclusion sets of process
attributes. The available inclusion sets are, for a given recording
session:
--kernel
option
Process ID (PID).
Virtual process ID (VPID).
This is the PID as seen by the application.
Unix user ID (UID).
Virtual Unix user ID (VUID).
This is the UID as seen by the application.
Unix group ID (GID).
Virtual Unix group ID (VGID).
This is the GID as seen by the application.
--userspace
option
VPID
VUID
VGID
When an event E
satisfies all the other explicit and implicit
conditions of an event rule ER
, ER
matches E
if
the attributes of the process for which LTTng creates E
are
all part of the inclusion sets of the recording session and domain
of ER
.
By default, on recording session creation (see lttng-create(1)), all processes are allowed to record events. In other words, all the inclusion sets of the recording session contain all the possible process attribute values.
If a given inclusion set IS
contains all the possible values
(--all
option), then using the track
command to add one or more
values V
to IS
:
Removes all the values from IS
.
This effectively makes IS
empty.
Adds V
to IS
.
Example: with the PID inclusion set, you can record all the system calls of a given process:
$ $ $
lttng enable-event --kernel --all --syscall lttng track --kernel --pid=2345 lttng start
See the “EXAMPLES” section below for usage examples.
Remove values from an inclusion set with the lttng-untrack(1) command.
This example operates on the Linux kernel process ID (PID) inclusion set of the current recording session to show how an inclusion set works.
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 is now:
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
Command:
$
lttng untrack --kernel --pid=7
Inclusion set is now:
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
Command:
$
lttng track --kernel --pid=1,5
Inclusion set is now:
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
Remove values from an inclusion set with the lttng-untrack(1) command.
See lttng(1) for GENERAL OPTIONS.
One of:
-k
, --kernel
Add values to one or more Linux kernel inclusion sets.
-u
, --userspace
Add values to one or more user space inclusion sets.
-p
[PID
[,PID
]…], --pid
[=PID
[,PID
]…]
For each PID
argument, add PID
to the process ID inclusion set
of the selected recording session and domain.
PID
is the process ID attribute of a process as seen from the root
PID namespace (see pid_namespaces(7)).
Only available with --kernel
option.
--vpid
[=VPID
[,VPID
]…]
For each VPID
argument, add VPID
to the virtual process ID
inclusion set of the selected recording session and domain.
VPID
is the virtual process ID attribute of a process as seen from
the PID namespace of the process (see pid_namespaces(7)).
--uid
[=USER
[,USER
]…]
For each USER
argument, add USER
to the user ID inclusion set of
the selected recording session and domain.
USER
is either:
The real user ID (see getuid(3)) of a process as seen from the root user namespace (see user_namespaces(7)).
A user name.
The connected LTTng session daemon (see lttng-sessiond(8)) performs the user name resolution on addition to the user ID inclusion set.
Only available with --kernel
option.
--vuid
[=VUSER
[,VUSER
]…]
For each VUSER
argument, add VUSER
to the virtual user ID
inclusion set of the selected recording session and domain.
VUSER
is either:
The real user ID (see getuid(3)) of a process as seen from the user namespace (see user_namespaces(7)).
A user name.
The connected LTTng session daemon (see lttng-sessiond(8)) performs the user name resolution on addition to the virtual user ID inclusion set.
--gid
[=GROUP
[,GROUP
]…]
For each GROUP
argument, add GROUP
to the group ID
inclusion set of the selected recording session and domain.
GROUP
is either:
The real group ID (see getgid(3)) of a process as seen from the root user namespace (see user_namespaces(7)).
A group name.
The connected LTTng session daemon (see lttng-sessiond(8)) performs the group name resolution on addition to the group ID inclusion set.
Only available with --kernel
option.
--vgid
[=VGROUP
[,VGROUP
]…]
For each VGROUP
argument, add VGROUP
to the virtual group ID
inclusion set of the selected recording session and domain.
VGROUP
is either:
The real group ID (see getgid(3)) of a process as seen from the user namespace (see user_namespaces(7)).
A group name.
The connected LTTng session daemon (see lttng-sessiond(8)) performs the group name resolution on addition to the virtual group ID inclusion set.
-h
, --help
Show help.
This option attempts to launch /usr/bin/man
to view this manual page.
Override the manual pager path with the LTTNG_MAN_BIN_PATH
environment
variable.
--list-options
List available command options and quit.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
LTTNG_ABORT_ON_ERROR
Set to 1
to abort the process after the first error is
encountered.
LTTNG_HOME
Path to the LTTng home directory.
Defaults to $HOME
.
Useful when the Unix user running the commands has a non-writable home directory.
LTTNG_MAN_BIN_PATH
Absolute path to the manual pager to use to read the LTTng
command-line help (with lttng-help(1) or with the
--help
option) instead of /usr/bin/man
.
LTTNG_SESSION_CONFIG_XSD_PATH
Path to the directory containing the session.xsd
recording session
configuration XML schema.
LTTNG_SESSIOND_PATH
Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.
The --sessiond-path
general option overrides this environment
variable.
$LTTNG_HOME/.lttngrc
Unix user’s LTTng runtime configuration.
This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.
$LTTNG_HOME/lttng-traces
Default output directory of LTTng traces in local and snapshot modes.
Override this path with the --output
option of the
lttng-create(1) command.
$LTTNG_HOME/.lttng
Unix user’s LTTng runtime and configuration directory.
$LTTNG_HOME/.lttng/sessions
Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).
/etc/lttng/sessions
Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).
Note:$LTTNG_HOME
defaults to the value of the HOME
environment
variable.
Example:Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session.
See the --pid
option.
$
lttng track --kernel --pid=1728,3775
Example:Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session.
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.