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