X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-track.1.txt;h=646b55cad5fb6a93d7c4df903a59fcdbf79af116;hp=899a6c4eadd9b2ef0da5b242a0c32d519f7f0a7f;hb=a92b6bcc41bafdf600ec412ce8e7c789121426d4;hpb=65226554a1fee74f1528058539b96ed3e77e5159 diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 899a6c4ea..646b55cad 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -1,5 +1,6 @@ lttng-track(1) ============== +:revdate: 04 November 2019 NAME @@ -10,8 +11,14 @@ lttng-track - Add one or more entries to an LTTng resource tracker SYNOPSIS -------- [verse] -*lttng* ['GENERAL OPTIONS'] *track* (option:--kernel | option:--userspace) - [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace) + [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | + option:--uid='UID'[,'UID'][,'USERNAME']... | + option:--gid='GID'[,'GID'][,'GROUPNAME']... | + option:--vpid='VPID'[,'VPID']... | + option:--vuid='VUID'[,'VUID'][,'USERNAME']... | + option:--vgid='VGID'[,'VGID'][,'GROUPNAME']... | + option:--all (option:--pid | option:--uid | option:--gid | option:--vpid | option:--vuid | option:--vgid)) DESCRIPTION @@ -21,25 +28,27 @@ resource tracker. A resource tracker is a _whitelist_ of resources. Tracked resources are allowed to emit events, provided those events are targeted by enabled -event rules (see linklttng:lttng-enable-event(1)). +event rules (see man:lttng-enable-event(1)). Tracker entries can be removed from the whitelist with -linklttng:lttng-untrack(1). +man:lttng-untrack(1). -As of this version, the only available tracker is the *PID tracker*. The -process ID (PID) tracker follows one or more process IDs; only the -processes with a tracked PID are allowed to emit events. By default, all -possible PIDs on the system are tracked: any process may emit enabled -events (equivalent of `lttng track --pid --all` for all domains). +The following tracker are available: PID, UID, GID, VPID, VUID, VGID. + +A tracker follows one or more IDs; only the processes with a tracked ID are +allowed to emit events. By default, all possible IDs on the system are tracked: +any process may emit enabled events (equivalent of `lttng track --pid --uid +--gid --vpid --vuid --vgid --all` for all domains). With the PID tracker, it is possible, for example, to record all system calls called by a given process: -------------------------------------------- -lttng enable-event --kernel --all --syscall -lttng track --kernel --pid=2345 -lttng start -------------------------------------------- +[role="term"] +---- +# lttng enable-event --kernel --all --syscall +# lttng track --kernel --pid=2345 +# lttng start +---- If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is the default state of all domains when creating a tracing session), then @@ -50,7 +59,7 @@ specified PIDs. Example ~~~~~~~ -Assume the maximum system PID is 7 for this example. +Assume the maximum system VPID is 7 for this example. Initial whitelist: @@ -60,9 +69,10 @@ Initial whitelist: Command: ------------------------------------ -lttng track --userspace --pid=3,6,7 ------------------------------------ +[role="term"] +---- +$ lttng track --userspace --vpid=3,6,7 +---- Whitelist: @@ -72,9 +82,10 @@ Whitelist: Command: ---------------------------------- -lttng untrack --userspace --pid=7 ---------------------------------- +[role="term"] +---- +$ lttng untrack --userspace --vpid=7 +---- Whitelist: @@ -84,9 +95,10 @@ Whitelist: Command: ---------------------------------- -lttng track --userspace --pid=1,5 ---------------------------------- +[role="term"] +---- +$ lttng track --userspace --vpid=1,5 +---- Whitelist: @@ -94,11 +106,11 @@ Whitelist: [ ] [1] [ ] [3] [ ] [5] [6] [ ] ------------------------------- -It should be noted that the PID tracker tracks the numeric process IDs. -Should a process with a given ID exit and another process be given this -ID, then the latter would also be allowed to emit events. +It should be noted that the VPID tracker tracks the numeric namespaced process +IDs. Should a process with a given ID exit and another process be given this ID, +then the latter would also be allowed to emit events. -See the linklttng:lttng-untrack(1) for more details about removing +See the man:lttng-untrack(1) for more details about removing entries. @@ -118,7 +130,7 @@ option:-u, option:--userspace:: Target ~~~~~~ -option:-s, option:--session='SESSION':: +option:-s 'SESSION', option:--session='SESSION':: Track resources in the tracing session named 'SESSION' instead of the current tracing session. @@ -126,15 +138,59 @@ option:-s, option:--session='SESSION':: Tracking ~~~~~~~~ option:-a, option:--all:: - Used in conjunction with an empty option:--pid option: track _all_ + Used in conjunction with an empty tracker option, e.g: options:--pid track _all_ process IDs (add all entries to the whitelist). -option:-p, option:--pid[='PID'[,'PID']...]:: +option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: Track process IDs 'PID' (add them to the current whitelist). + PID is the non-namespaced value for the process. + The 'PID' argument must be omitted when also using the option:--all option. +option:-p ['UID'[,'UID']...], option:--uid[='UID'[,'UID'][,'USERNAME']...]:: + Track process IDs 'UID' (add them to the current whitelist). + User name can also be used, name resolution is performed by + lttng-sessiond. + UID is the non-namespaced user id value for the process. ++ +The 'UID' argument must be omitted when also using the option:--all +option. + +option:-p ['GID'[,'GID']...], option:--gid[='GID'[,'GID'][,'GROUPNAME']...]:: + Track process IDs 'GID' (add them to the current whitelist). + Group name can also be used, name resolution is performed by + lttng-sessiond. + GID is the non-namespaced group id value for the process. ++ +The 'GID' argument must be omitted when also using the option:--all +option. + +option:-p ['VPID'[,'VPID']...], option:--vpid[='VPID'[,'VPID']...]:: + Track process IDs 'VPID' (add them to the current whitelist). + VPID is the namespaced PID of the process for its current context. ++ +The 'VPID' argument must be omitted when also using the option:--all +option. + +option:-p ['VUID'[,'VUID']...], option:--vuid[='VUID'[,'VUID'][,'USERNAME']...]:: + Track process IDs 'VUID' (add them to the current whitelist). + User name can also be used, name resolution is performed by + lttng-sessiond. + VUID is the namespaced UID of the process for its current context. ++ +The 'VUID' argument must be omitted when also using the option:--all +option. + +option:-p ['VGID'[,'VGID']...], option:--vgid[='VGID'[,'VGID'][,'GROUPNAME']...]:: + Track process IDs 'VGID' (add them to the current whitelist). + Group name can also be used, name resolution is performed by + lttng-sessiond. + VGID is the namespaced GID of the process for its current context. ++ +The 'VGID' argument must be omitted when also using the option:--all +option. + include::common-cmd-help-options.txt[] @@ -144,5 +200,5 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -linklttng:lttng-untrack(1), -linklttng:lttng(1) +man:lttng-untrack(1), +man:lttng(1)