# lttng-track

## NAME



           lttng-track - Add one or more entries to an LTTng resource tracker
    


## SYNOPSIS



           **lttng**[_GENERAL OPTIONS_] **track**(**--kernel** | **--userspace**)
                 [**--session** =_SESSION_] (**--pid** =_PID_[,_PID_]... | **--all --pid**)
    


## DESCRIPTION



           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.
    
       **Example**
           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.
    


## OPTIONS



           General options are described in lttng(1).
    
       **Domain**
           One of:
    
           **-k** , **--kernel**
               Track resources in the Linux kernel domain.
    
           **-u** , **--userspace**
               Track resources in the user space domain.
    
       **Target**
           **-s** _SESSION_ , **--session** =_SESSION_
               Track resources in the tracing session named _SESSION_ instead
               of the current tracing session.
    
       **Tracking**
           **-a** , **--all**
               Used in conjunction with an empty **--pid** option: track _all_
               process IDs (add all entries to the whitelist).
    
           **-p**[_PID_[,_PID_]...], **--pid**[=_PID_[,_PID_]...]
               Track process IDs _PID_ (add them to the current whitelist).
    
               The _PID_ argument must be omitted when also using the **--all**
               option.
    
       **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**
    


## 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.
    


* * *