doc/man/lttng-untrack.1.txt

   1 lttng-untrack(1)
   2 ================
   3 :revdate: 1 May 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 tracing session named 'SESSION'.
  44
  45 Without the option:--session option::
  46     The current tracing session (see man:lttng-concepts(7) to learn more
  47     about the current tracing session).
  48
  49 See man:lttng-concepts(7) to learn more about tracing 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
  56
  57 Inclusion set example
  58 ~~~~~~~~~~~~~~~~~~~~~
  59 A common operation is to create a tracing session (see
  60 man:lttng-create(1)), remove all the entries from the Linux kernel
  61 process ID inclusion set, start tracing, and then manually add PIDs
  62 while the tracing session is active.
  63
  64 Assume the maximum system PID is 7 for this example.
  65
  66 . Command:
  67 +
  68 [role="term"]
  69 ----
  70 $ lttng create
  71 ----
  72 +
  73 Initial inclusion set:
  74 +
  75 -------------------------------
  76 [0] [1] [2] [3] [4] [5] [6] [7]
  77 -------------------------------
  78
  79 . Command:
  80 +
  81 [role="term"]
  82 ----
  83 $ lttng untrack --kernel --all --pid
  84 ----
  85 +
  86 Inclusion set:
  87 +
  88 -------------------------------
  89 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
  90 -------------------------------
  91
  92 . Commands:
  93 +
  94 [role="term"]
  95 ----
  96 $ lttng enable-event --kernel ...
  97 $ lttng start
  98 $ # ...
  99 $ lttng track --kernel --pid=3,5
 100 ----
 101 +
 102 Inclusion set:
 103 +
 104 -------------------------------
 105 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
 106 -------------------------------
 107
 108 . Command:
 109 +
 110 [role="term"]
 111 ----
 112 $ lttng track --kernel --pid=2
 113 ----
 114 +
 115 Inclusion set:
 116 +
 117 -------------------------------
 118 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
 119 -------------------------------
 120
 121
 122 include::common-lttng-cmd-options-head.txt[]
 123
 124
 125 Tracing domain
 126 ~~~~~~~~~~~~~~
 127 One of:
 128
 129 option:-k, option:--kernel::
 130     Remove values from one or more Linux kernel inclusion sets.
 131
 132 option:-u, option:--userspace::
 133     Remove values from one or more user space inclusion sets.
 134
 135
 136 Recording target
 137 ~~~~~~~~~~~~~~~~
 138 option:-s 'SESSION', option:--session='SESSION'::
 139     Remove values from one or more inclusion sets of the tracing session
 140     named 'SESSION' instead of the current tracing session.
 141
 142
 143 Inclusion set selection
 144 ~~~~~~~~~~~~~~~~~~~~~~~
 145 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
 146     For each 'PID' argument, remove 'PID' from the process ID inclusion
 147     set of the selected tracing session and domain.
 148 +
 149 'PID' is the process ID attribute of a process as seen from the root
 150 PID namespace (see man:pid_namespaces(7)).
 151 +
 152 Only available with option:--kernel option.
 153
 154 option:--vpid[='VPID'[,'VPID']...]::
 155     For each 'VPID' argument, remove 'VPID' from the virtual process ID
 156     inclusion set of the selected tracing session and domain.
 157 +
 158 'VPID' is the virtual process ID attribute of a process as seen from
 159 the PID namespace of the process (see man:pid_namespaces(7)).
 160
 161 option:--uid[='USER'[,'USER']...]::
 162     For each 'USER' argument, remove 'USER' from the user ID inclusion
 163     set of the selected tracing session and domain.
 164 +
 165 'USER' is either:
 166 +
 167 --
 168 * The real user ID (see man:getuid(3)) of a process as seen
 169   from the root user namespace (see man:user_namespaces(7)).
 170
 171 * A user name.
 172 +
 173 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 174 the user name resolution on removal from the user ID inclusion set.
 175 --
 176 +
 177 Only available with option:--kernel option.
 178
 179 option:--vuid[='VUSER'[,'VUSER']...]::
 180     For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
 181     inclusion set of the selected tracing session and domain.
 182 +
 183 'VUSER' is either:
 184 +
 185 --
 186 * The real user ID (see man:getuid(3)) of a process as seen
 187   from the user namespace (see man:user_namespaces(7)).
 188
 189 * A user name.
 190 +
 191 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 192 the user name resolution on removal from the virtual user ID inclusion
 193 set.
 194 --
 195
 196 option:--gid[='GROUP'[,'GROUP']...]::
 197     For each 'GROUP' argument, remove 'GROUP' from the group ID
 198     inclusion set of the selected tracing session and domain.
 199 +
 200 'GROUP' is either:
 201 +
 202 --
 203 * The real group ID (see man:getgid(3)) of a process as seen from the
 204   root user namespace (see man:user_namespaces(7)).
 205
 206 * A group name.
 207 +
 208 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 209 the group name resolution on removal from the group ID inclusion set.
 210 --
 211 +
 212 Only available with option:--kernel option.
 213
 214 option:--vgid[='VGROUP'[,'VGROUP']...]::
 215     For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
 216     ID inclusion set of the selected tracing session and domain.
 217 +
 218 'VGROUP' is either:
 219 +
 220 --
 221 * The real group ID (see man:getgid(3)) of a process as seen
 222   from the user namespace (see man:user_namespaces(7)).
 223
 224 * A group name.
 225 +
 226 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
 227 the group name resolution on removal from the virtual group ID inclusion
 228 set.
 229 --
 230
 231
 232 Inclusion set operation
 233 ~~~~~~~~~~~~~~~~~~~~~~~
 234 option:-a, option:--all::
 235     With one or more empty option:--pid, option:--vpid, option:--uid,
 236     option:--vuid, option:--gid, and option:--vgid options: clear the
 237     selected inclusion sets.
 238
 239
 240 include::common-lttng-cmd-help-options.txt[]
 241
 242
 243 include::common-lttng-cmd-after-options.txt[]
 244
 245
 246 include::common-footer.txt[]
 247
 248
 249 SEE ALSO
 250 --------
 251 man:lttng(1),
 252 man:lttng-track(1),
 253 man:lttng-concepts(7)