lttng-untrack — Remove one or more entries from an LTTng resource tracker
Synopsis
lttng [GENERAL OPTIONS] untrack (--kernel | --userspace)
[--session=SESSION] (--pid=PID[,PID]... | --all --pid)Description
The lttng untrack commands removes one or more entries from a resource tracker.
See lttng-track(1) to learn more about LTTng trackers.
The untrack command removes specific resources from a tracker. The resources to remove must have been precedently added by lttng-track(1). It is also possible to remove all the resources from the whitelist using the --all option.
As of this version, the only available tracker is the PID tracker.
Example
One common operation is to create a tracing session (see lttng-create(1)), remove all the entries from the PID tracker whitelist, 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 whitelist:
[0] [1] [2] [3] [4] [5] [6] [7]
Command:
$ lttng untrack --userspace --pid --all
Whitelist:
[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
Commands:
$ lttng enable-event --userspace ... $ lttng start $ # ... $ lttng track --userspace --pid=3,5
Whitelist:
[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
Command:
$ lttng track --userspace --pid=2
Whitelist:
[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
Options
General options are described in lttng(1).
Domain
One of:
- -k, --kernel
Untrack resources tracked in the Linux kernel domain.
- -u, --userspace
Untrack resources tracked in the user space domain.
Target
- -s, --session=SESSION
Untrack resources in the tracing session named SESSION instead of the current tracing session.
Untracking
Program information
- -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.
Environment Variables
- 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.
Files
- $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)).
- /usr/local/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.
Exit Status
- 0
Success
- 1
Command error
- 2
Undefined command
- 3
Fatal error
- 4
Command warning (something went wrong during the command)
Bugs
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
Resources
- 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
Copyrights
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.
Thanks
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.