doc/man/lttng-untrack.1.txt

   1 lttng-untrack(1)
   2 ================
   3
   4
   5 NAME
   6 ----
   7 lttng-untrack - Remove one or more property values from an LTTng process tracker
   8
   9
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 Untrack processes for Linux kernel channels:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
  17       [option:--pid='PID'[,'PID']... | option:--pid option:--all]
  18       [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
  19       [option:--uid='USER'[,'USER']... | option:--uid option:--all]
  20       [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
  21       [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all]
  22       [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
  23
  24 Untrack processes for user space channels:
  25
  26 [verse]
  27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
  28       [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
  29       [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
  30       [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
  31
  32
  33 DESCRIPTION
  34 -----------
  35 The `lttng untrack` commands removes one or more property values from an
  36 LTTng process tracker.
  37
  38 See man:lttng-track(1) to learn more about LTTng process trackers.
  39
  40 The `lttng untrack` command removes specific property values from a
  41 process tracker's whitelist. The property values to remove must have
  42 been precedently added by man:lttng-track(1). It is also possible to
  43 remove all the values of a given property from the whitelist with the
  44 option:--all option following the specific property option.
  45
  46 The available process properties are:
  47
  48 option:--pid::
  49     Process ID as seen by the Linux kernel (root namespace).
  50
  51 option:--uid::
  52     User ID or name as seen by the Linux kernel (root namespace).
  53
  54 option:--gid::
  55     Group ID or name as seen by the Linux kernel (root namespace).
  56
  57 option:--vpid::
  58     Process ID as seen by the traced process.
  59
  60 option:--vuid::
  61     User ID or name as seen by the traced process.
  62
  63 option:--vgid::
  64     Group ID or name as seen by the traced process.
  65
  66
  67 Understanding the whitelist
  68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69 One common operation is to create a tracing session (see
  70 man:lttng-create(1)), remove all the process ID property values from the
  71 process tracker whitelist, start tracing, and then manually track
  72 processes with a given PID while tracing is active.
  73
  74 Assume the maximum system PID is 7 for this example.
  75
  76 Command:
  77
  78 [role="term"]
  79 ----
  80 $ lttng create
  81 ----
  82
  83 Initial whitelist:
  84
  85 -------------------------------
  86 [0] [1] [2] [3] [4] [5] [6] [7]
  87 -------------------------------
  88
  89 Command:
  90
  91 [role="term"]
  92 ----
  93 $ lttng untrack --kernel --pid --all
  94 ----
  95
  96 Whitelist:
  97
  98 -------------------------------
  99 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
 100 -------------------------------
 101
 102 Commands:
 103
 104 [role="term"]
 105 ----
 106 $ lttng enable-event --kernel ...
 107 $ lttng start
 108 $ # ...
 109 $ lttng track --kernel --pid=3,5
 110 ----
 111
 112 Whitelist:
 113
 114 -------------------------------
 115 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
 116 -------------------------------
 117
 118 Command:
 119
 120 [role="term"]
 121 ----
 122 $ lttng track --kernel --pid=2
 123 ----
 124
 125 Whitelist:
 126
 127 -------------------------------
 128 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
 129 -------------------------------
 130
 131
 132 include::common-cmd-options-head.txt[]
 133
 134
 135 Domain
 136 ~~~~~~
 137 One of:
 138
 139 option:-k, option:--kernel::
 140     Untrack processes for Linux kernel channels.
 141
 142 option:-u, option:--userspace::
 143     Untrack processes for user space channels.
 144
 145
 146 Target
 147 ~~~~~~
 148 option:-s, option:--session='SESSION'::
 149     Untrack processes in the tracing session named 'SESSION' instead of
 150     the current tracing session.
 151
 152
 153 Process property
 154 ~~~~~~~~~~~~~~~~
 155 option:-a, option:--all::
 156     Following any of the property options below (without an option's
 157     argument): remove _all_ possible values of this property from the
 158     process tracker's whitelist.
 159
 160 option:--pid[='PID'[,'PID']...]::
 161     Remove process ID 'PID', as seen by the Linux kernel (root
 162     namespace), from the tracker's whitelist.
 163
 164 option:--uid[='USER'[,'USER']...]::
 165     Remove user ID or name 'USER', as seen by the Linux kernel (root
 166     namespace), from the tracker's whitelist.
 167
 168 option:--gid[='GROUP'[,'GROUP']...]::
 169     Remove group ID or name 'GROUP', as seen by the Linux kernel (root
 170     namespace), from the tracker's whitelist.
 171
 172 option:--vpid[='PID'[,'PID']...]::
 173     Remove process ID 'VPID', as seen by the traced process, from the
 174     tracker's whitelist.
 175
 176 option:--vuid[='USER'[,'USER']...]::
 177     Remove user ID or name 'USER', as seen by the traced process, from
 178     the tracker's whitelist.
 179
 180 option:--vgid[='GROUP'[,'GROUP']...]::
 181     Remove group ID or name 'GROUP', as seen by the traced process, from
 182     the tracker's whitelist.
 183
 184
 185 include::common-cmd-help-options.txt[]
 186
 187
 188 include::common-cmd-footer.txt[]
 189
 190
 191 SEE ALSO
 192 --------
 193 man:lttng-track(1),
 194 man:lttng(1)