DOKK / manpages / debian 11 / lttng-tools / lttng-untrack.1.en
LTTNG-UNTRACK(1) LTTng Manual LTTNG-UNTRACK(1)

lttng-untrack - Remove one or more values from an LTTng process attribute tracker

Remove specific process attribute values from a Linux kernel domain tracker:

lttng [GENERAL OPTIONS] untrack --kernel


      (--pid=PID[,PID]... | --vpid=VPID[,VPID]... |


      --uid=UID[,UID]... | --vuid=VUID[,VUID]... |


      --gid=GID[,GID]... | --vgid=VGID[,VGID]... )...

Remove all possible process attribute values from a Linux kernel domain tracker:

lttng [GENERAL OPTIONS] untrack --kernel


      --all (--pid | --vpid | --uid |


      --vuid | --gid | --vgid )...

Remove specific process attribute values from a user space domain tracker:

lttng [GENERAL OPTIONS] untrack --userspace


      (--vpid=VPID[,VPID]... | --vuid=VUID[,VUID]... | --vgid=VGID[,VGID]...)...

Remove all possible process attribute values from a user space domain tracker:

lttng [GENERAL OPTIONS] untrack --userspace


      --all (--vpid | --vgid | --vuid)...

The lttng untrack commands removes one or more values from a process attribute tracker.

See lttng-track(1) to learn more about LTTng trackers.

The untrack command removes specific process attribute values from a tracker’s inclusion set. The attributes to remove must have been precedently added by lttng-track(1). It is also possible to remove all the possible values of a process attribute from the inclusion set using the --all option.

One common operation is to create a tracing session (see lttng-create(1)), remove all the entries from the PID tracker inclusion set, start tracing, and then manually track PIDs while tracing is active.

Assume the maximum system PID is 7 for this example.

Command:

$ lttng create

Initial inclusion set:

[0] [1] [2] [3] [4] [5] [6] [7]

Command:

$ lttng untrack --kernel --pid --all

inclusion set:

[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]

Commands:

$ lttng enable-event --kernel ...
$ lttng start
$ # ...
$ lttng track --kernel --pid=3,5

inclusion set:

[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]

Command:

$ lttng track --kernel --pid=2

inclusion set:

[ ] [ ] [2] [3] [ ] [5] [ ] [ ]

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.

-s SESSION, --session=SESSION

Untrack process attributes in the tracing session named SESSION instead of the current tracing session.

-a, --all

Used in conjunction with a single, empty --pid, --vpid, --uid, --vuid, --gid, or --vgid option: untrack all possible process attribute values (remove all values from the inclusion set).

-p [PID[,PID]...], --pid[=PID[,PID]...]

Untrack process ID values PID (remove them from 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]...]

Untrack virtual process ID values VPID (remove them from 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]...]

Untrack user ID process attribute values USER (remove them from 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. No name resolution is performed; USER will be matched against the names in the inclusion set.

The USER argument must be omitted when also using the --all option.

--vuid[=USER[,USER]...]

Untrack virtual user ID process attribute values USER (remove them from 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. No name resolution is performed; USER will be matched against the names in the inclusion set.

The USER argument must be omitted when also using the --all option.

--gid[=GROUP[,GROUP]...]

Untrack group ID process attribute values GROUP (remove them from 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. No name resolution is performed; GROUP will be matched against the names in the inclusion set.

The GROUP argument must be omitted when also using the --all option.

--vgid[=GROUP[,GROUP]...]

Untrack virtual group ID process attribute values GROUP(remove them from 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. No name resolution is performed; GROUP will be matched against the names in the 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.

0

Success

1

Command error

2

Undefined command

3

Fatal error

4

Command warning (something went wrong during the command)

If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.

•LTTng project website <https://lttng.org>

•LTTng documentation <https://lttng.org/docs>

•Git repositories <http://git.lttng.org>

•GitHub organization <http://github.com/lttng>

•Continuous integration <http://ci.lttng.org/>

•Mailing list <http://lists.lttng.org> for support and development: lttng-dev@lists.lttng.org

•IRC channel <irc://irc.oftc.net/lttng>: #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 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> 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.

lttng-track(1), lttng(1)

4 March 2020 LTTng 2.12.3