doc/man/lttng-untrack.1.txt

   1 lttng-untrack(1)
   2 ================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-untrack - Disallow specific processes to record LTTng events
   9
  10
  11 SYNOPSIS
  12 --------
  13 Disallow specific processes to record Linux kernel events:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
  17       (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
  18        option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
  19        option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
  20
  21 [verse]
  22 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
  23       option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...
  24
  25 Disallow specific processes to record user space events:
  26
  27 [verse]
  28 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
  29       (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
  30        option:--vgid=VGROUP[,VGROUP]...)...
  31
  32 [verse]
  33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
  34       option:--all (option:--vpid | option:--vgid | option:--vuid)...
  35
  36
  37 DESCRIPTION
  38 -----------
  39 The `lttng untrack` command disallows one or more processes to record
  40 LTTng events based on their attributes within:
  41
  42 With the option:--session='SESSION' option::
  43     The recording session named 'SESSION'.
  44
  45 Without the option:--session option::
  46     The current recording session (see man:lttng-concepts(7) to learn
  47     more about the current recording session).
  48
  49 See man:lttng-concepts(7) to learn more about recording sessions and
  50 recording event rules.
  51
  52 The `untrack` command removes values from _inclusion sets_ of process
  53 attributes. See man:lttng-track(1) to learn more about inclusion sets.
  54
  55 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  56
  57
  58 Inclusion set example
  59 ~~~~~~~~~~~~~~~~~~~~~
  60 A common operation is to create a recording session (see
  61 man:lttng-create(1)), remove all the entries from the Linux kernel
  62 process ID inclusion set, start recording, and then manually add PIDs
  63 while the recording session is active.
  64
  65 Assume the maximum system PID is 7 for this example.
  66
  67 . Command:
  68 +
  69 [role="term"]
  70 ----
  71 $ lttng create
  72 ----
  73 +
  74 Initial inclusion set:
  75 +
  76 -------------------------------
  77 [0] [1] [2] [3] [4] [5] [6] [7]
  78 -------------------------------
  79
  80 . Command:
  81 +
  82 [role="term"]
  83 ----
  84 $ lttng untrack --kernel --all --pid
  85 ----
  86 +
  87 Inclusion set:
  88 +
  89 -------------------------------
  90 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
  91 -------------------------------
  92
  93 . Commands:
  94 +
  95 [role="term"]
  96 ----
  97 $ lttng enable-event --kernel ...
  98 $ lttng start
  99 $ # ...
 100 $ lttng track --kernel --pid=3,5
 101 ----
 102 +
 103 Inclusion set:
 104 +
 105 -------------------------------
 106 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
 107 -------------------------------
 108
 109 . Command:
 110 +
 111 [role="term"]
 112 ----
 113 $ lttng track --kernel --pid=2
 114 ----
 115 +
 116 Inclusion set:
 117 +
 118 -------------------------------
 119 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
 120 -------------------------------
 121
 122
 123 include::common-lttng-cmd-options-head.txt[]
 124
 125
 126 Tracing domain
 127 ~~~~~~~~~~~~~~
 128 One of:
 129
 130 option:-k, option:--kernel::
 131     Remove values from one or more Linux kernel inclusion sets.
 132
 133 option:-u, option:--userspace::
 134     Remove values from one or more user space inclusion sets.
 135
 136
 137 Recording target
 138 ~~~~~~~~~~~~~~~~
 139 option:-s 'SESSION', option:--session='SESSION'::
 140     Remove values from one or more inclusion sets of the recording
 141     session named 'SESSION' instead of the current recording session.
 142
 143
 144 Inclusion set selection
 145 ~~~~~~~~~~~~~~~~~~~~~~~
 146 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
 147     For each 'PID' argument, remove 'PID' from the process ID inclusion
 148     set of the selected recording session and domain.
 149 +
 150 'PID' is the process ID attribute of a process as seen from the root
 151 PID namespace (see man:pid_namespaces(7)).
 152 +
 153 Only available with option:--kernel option.
 154
 155 option:--vpid[='VPID'[,'VPID']...]::
 156     For each 'VPID' argument, remove 'VPID' from the virtual process ID
 157     inclusion set of the selected recording session and domain.
 158 +
 159 'VPID' is the virtual process ID attribute of a process as seen from
 160 the PID namespace of the process (see man:pid_namespaces(7)).
 161
 162 option:--uid[='USER'[,'USER']...]::
 163     For each 'USER' argument, remove 'USER' from the user ID inclusion
 164     set of the selected recording session and domain.
 165 +
 166 'USER' is either:
 167 +
 168 --
 169 * The real user ID (see man:getuid(3)) of a process as seen
 170   from the root user namespace (see man:user_namespaces(7)).
 171
 172 * A user name.
 173 +
 174 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 175 the user name resolution on removal from the user ID inclusion set.
 176 --
 177 +
 178 Only available with option:--kernel option.
 179
 180 option:--vuid[='VUSER'[,'VUSER']...]::
 181     For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
 182     inclusion set of the selected recording session and domain.
 183 +
 184 'VUSER' is either:
 185 +
 186 --
 187 * The real user ID (see man:getuid(3)) of a process as seen
 188   from the user namespace (see man:user_namespaces(7)).
 189
 190 * A user name.
 191 +
 192 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 193 the user name resolution on removal from the virtual user ID inclusion
 194 set.
 195 --
 196
 197 option:--gid[='GROUP'[,'GROUP']...]::
 198     For each 'GROUP' argument, remove 'GROUP' from the group ID
 199     inclusion set of the selected recording session and domain.
 200 +
 201 'GROUP' is either:
 202 +
 203 --
 204 * The real group ID (see man:getgid(3)) of a process as seen from the
 205   root user namespace (see man:user_namespaces(7)).
 206
 207 * A group name.
 208 +
 209 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 210 the group name resolution on removal from the group ID inclusion set.
 211 --
 212 +
 213 Only available with option:--kernel option.
 214
 215 option:--vgid[='VGROUP'[,'VGROUP']...]::
 216     For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
 217     ID inclusion set of the selected recording session and domain.
 218 +
 219 'VGROUP' is either:
 220 +
 221 --
 222 * The real group ID (see man:getgid(3)) of a process as seen
 223   from the user namespace (see man:user_namespaces(7)).
 224
 225 * A group name.
 226 +
 227 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 228 the group name resolution on removal from the virtual group ID inclusion
 229 set.
 230 --
 231
 232
 233 Inclusion set operation
 234 ~~~~~~~~~~~~~~~~~~~~~~~
 235 option:-a, option:--all::
 236     With one or more empty option:--pid, option:--vpid, option:--uid,
 237     option:--vuid, option:--gid, and option:--vgid options: clear the
 238     selected inclusion sets.
 239
 240
 241 include::common-lttng-cmd-help-options.txt[]
 242
 243
 244 include::common-lttng-cmd-after-options.txt[]
 245
 246
 247 [[examples]]
 248 EXAMPLES
 249 --------
 250 .Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current recording session.
 251 ====
 252 See the option:--pid option.
 253
 254 [role="term"]
 255 ----
 256 $ lttng untrack --kernel --pid=1728,3775
 257 ----
 258 ====
 259
 260 .Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific recording session.
 261 ====
 262 See the option:--vgid and option:--session options.
 263
 264 [role="term"]
 265 ----
 266 $ lttng untrack --userspace --session=my-session \
 267                 --vgid=docker,mysql
 268 ----
 269 ====
 270
 271 .Remove all the user IDs from the Linux kernel user ID inclusion set of the current recording session.
 272 ====
 273 See the option:--all and option:--uid options.
 274
 275 [role="term"]
 276 ----
 277 $ lttng untrack --kernel --all --uid
 278 ----
 279 ====
 280
 281
 282 include::common-footer.txt[]
 283
 284
 285 SEE ALSO
 286 --------
 287 man:lttng(1),
 288 man:lttng-track(1),
 289 man:lttng-concepts(7)