doc/man/lttng-untrack.1.txt

   1 lttng-untrack(1)
   2 ================
   3 :revdate: 4 March 2020
   4
   5
   6 NAME
   7 ----
   8 lttng-untrack - Remove one or more values from an LTTng process attribute tracker
   9
  10
  11 SYNOPSIS
  12 --------
  13 Remove specific process attribute values from a Linux kernel domain tracker:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
  17       (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
  18       option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... |
  19       option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )...
  20
  21 Remove all possible process attribute values from a Linux kernel domain tracker:
  22
  23 [verse]
  24 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
  25       option:--all (option:--pid | option:--vpid | option:--uid |
  26       option:--vuid | option:--gid | option:--vgid )...
  27
  28 Remove specific process attribute values from a user space domain tracker:
  29
  30 [verse]
  31 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
  32       (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
  33
  34 Remove all possible process attribute values from a user space domain tracker:
  35
  36 [verse]
  37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
  38       option:--all (option:--vpid | option:--vgid | option:--vuid)...
  39
  40
  41 DESCRIPTION
  42 -----------
  43 The `lttng untrack` commands removes one or more values from a
  44 process attribute tracker.
  45
  46 See man:lttng-track(1) to learn more about LTTng trackers.
  47
  48 The untrack command removes specific process attribute values from a
  49 tracker's inclusion set. The attributes to remove must have been
  50 precedently added by man:lttng-track(1). It is also possible to remove
  51 all the possible values of a process attribute from the inclusion set
  52 using the option:--all option.
  53
  54
  55 Example
  56 ~~~~~~~
  57 One common operation is to create a tracing session
  58 (see man:lttng-create(1)), remove all the entries from the PID
  59 tracker inclusion set, start tracing, and then manually track PIDs
  60 while tracing is active.
  61
  62 Assume the maximum system PID is 7 for this example.
  63
  64 Command:
  65
  66 [role="term"]
  67 ----
  68 $ lttng create
  69 ----
  70
  71 Initial inclusion set:
  72
  73 -------------------------------
  74 [0] [1] [2] [3] [4] [5] [6] [7]
  75 -------------------------------
  76
  77 Command:
  78
  79 [role="term"]
  80 ----
  81 $ lttng untrack --kernel --pid --all
  82 ----
  83
  84 inclusion set:
  85
  86 -------------------------------
  87 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
  88 -------------------------------
  89
  90 Commands:
  91
  92 [role="term"]
  93 ----
  94 $ lttng enable-event --kernel ...
  95 $ lttng start
  96 $ # ...
  97 $ lttng track --kernel --pid=3,5
  98 ----
  99
 100 inclusion set:
 101
 102 -------------------------------
 103 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
 104 -------------------------------
 105
 106 Command:
 107
 108 [role="term"]
 109 ----
 110 $ lttng track --kernel --pid=2
 111 ----
 112
 113 inclusion set:
 114
 115 -------------------------------
 116 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
 117 -------------------------------
 118
 119
 120 include::common-cmd-options-head.txt[]
 121
 122
 123 Domain
 124 ~~~~~~
 125 One of:
 126
 127 option:-k, option:--kernel::
 128     Track process attributes in the Linux kernel domain.
 129
 130 option:-u, option:--userspace::
 131     Track process attributes in the user space domain.
 132
 133
 134 Target
 135 ~~~~~~
 136 option:-s 'SESSION', option:--session='SESSION'::
 137     Untrack process attributes in the tracing session named 'SESSION'
 138     instead of the current tracing session.
 139
 140
 141 Untracking
 142 ~~~~~~~~~~
 143 option:-a, option:--all::
 144     Used in conjunction with a single, empty option:--pid,
 145     option:--vpid, option:--uid, option:--vuid, option:--gid,
 146     or option:--vgid option: untrack _all_ possible process attribute
 147     values (remove all values from the inclusion set).
 148
 149 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
 150     Untrack process ID values 'PID' (remove them from the process ID
 151     inclusion set).
 152 +
 153 'PID' is the process ID attribute of a process as seen from the _root
 154 PID namespace_ (see man:pid_namespaces(7)). It can only be used with
 155 the option:--kernel domain option.
 156 +
 157 The 'PID' argument must be omitted when also using the option:--all
 158 option.
 159
 160 option:--vpid[='VPID'[,'VPID']...]::
 161     Untrack virtual process ID values 'VPID' (remove them from the
 162     virtual process ID inclusion set).
 163 +
 164 'VPID' is the virtual process ID attribute of a process as seen from
 165 the _PID namespace_ of the process (see man:pid_namespaces(7)).
 166 +
 167 The 'VPID' argument must be omitted when also using the option:--all
 168 option.
 169
 170 option:--uid[='USER'[,'USER']...]::
 171     Untrack user ID process attribute values 'USER' (remove them from
 172     the user ID inclusion set).
 173 +
 174 'USER' is the real user ID (see man:getuid(3)) of a process as seen
 175 from the _root user namespace_ (see man:user_namespaces(7)). It can
 176 only be used with the option:--kernel domain option.
 177 +
 178 'USER' can also be a user name. No name resolution is performed;
 179 'USER' will be matched against the names in the inclusion set.
 180 +
 181 The 'USER' argument must be omitted when also using the option:--all
 182 option.
 183
 184 option:--vuid[='USER'[,'USER']...]::
 185     Untrack virtual user ID process attribute values 'USER' (remove
 186     them from the virtual user ID inclusion set).
 187 +
 188 'USER' is the real user ID (see man:getuid(3)) of a process as seen
 189 from the _user namespace_ of the process (see man:user_namespaces(7)).
 190 +
 191 'USER' can also be a user name. No name resolution is performed;
 192 'USER' will be matched against the names in the inclusion set.
 193 +
 194 The 'USER' argument must be omitted when also using the option:--all
 195 option.
 196
 197 option:--gid[='GROUP'[,'GROUP']...]::
 198     Untrack group ID process attribute values 'GROUP' (remove them
 199     from the group ID inclusion set).
 200 +
 201 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
 202 from the _root user namespace_ (see man:user_namespaces(7)). It can
 203 only be used with the option:--kernel domain option.
 204 +
 205 'GROUP' can also be a group name. No name resolution is performed;
 206 'GROUP' will be matched against the names in the inclusion set.
 207 +
 208 The 'GROUP' argument must be omitted when also using the option:--all
 209 option.
 210
 211 option:--vgid[='GROUP'[,'GROUP']...]::
 212     Untrack virtual group ID process attribute values 'GROUP'(remove
 213     them from the virtual group ID inclusion set).
 214 +
 215 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
 216 from the _user namespace_ of the process (see man:user_namespaces(7)).
 217 +
 218 'GROUP' can also be a group name. No name resolution is performed;
 219 'GROUP' will be matched against the names in the inclusion set.
 220 +
 221 The 'GROUP' argument must be omitted when also using the option:--all
 222 option.
 223
 224
 225 include::common-cmd-help-options.txt[]
 226
 227
 228 include::common-cmd-footer.txt[]
 229
 230
 231 SEE ALSO
 232 --------
 233 man:lttng-track(1),
 234 man:lttng(1)