projects / lttng-tools.git / blame
| Commit | Line | Data |
|---|---|---|
| 65226554 PP |
1 | lttng-track(1) |
| 2 | ============== | |
| 3 | ||
| 4 | ||
| 5 | NAME | |
| 6 | ---- | |
| 7 | lttng-track - Add one or more entries to an LTTng resource tracker | |
| 8 | ||
| 9 | ||
| 10 | SYNOPSIS | |
| 11 | -------- | |
| 12 | [verse] | |
| 13 | *lttng* ['GENERAL OPTIONS'] *track* (option:--kernel | option:--userspace) | |
| 14 | [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid) | |
| 15 | ||
| 16 | ||
| 17 | DESCRIPTION | |
| 18 | ----------- | |
| 19 | The `lttng track` commands adds one or more entries to a | |
| 20 | resource tracker. | |
| 21 | ||
| 22 | A resource tracker is a _whitelist_ of resources. Tracked resources are | |
| 23 | allowed to emit events, provided those events are targeted by enabled | |
| 24 | event rules (see linklttng:lttng-enable-event(1)). | |
| 25 | ||
| 26 | Tracker entries can be removed from the whitelist with | |
| 27 | linklttng:lttng-untrack(1). | |
| 28 | ||
| 29 | As of this version, the only available tracker is the *PID tracker*. The | |
| 30 | process ID (PID) tracker follows one or more process IDs; only the | |
| 31 | processes with a tracked PID are allowed to emit events. By default, all | |
| 32 | possible PIDs on the system are tracked: any process may emit enabled | |
| 33 | events (equivalent of `lttng track --pid --all` for all domains). | |
| 34 | ||
| 35 | With the PID tracker, it is possible, for example, to record all system | |
| 36 | calls called by a given process: | |
| 37 | ||
| d4f093aa | 38 | [role="term"] |
| 65226554 PP |
39 | ------------------------------------------- |
| 40 | lttng enable-event --kernel --all --syscall | |
| 41 | lttng track --kernel --pid=2345 | |
| 42 | lttng start | |
| 43 | ------------------------------------------- | |
| 44 | ||
| 45 | If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is | |
| 46 | the default state of all domains when creating a tracing session), then | |
| 47 | using the track command with one or more specific PIDs has the effect of | |
| 48 | first removing all the PIDs from the whitelist, then adding the | |
| 49 | specified PIDs. | |
| 50 | ||
| 51 | ||
| 52 | Example | |
| 53 | ~~~~~~~ | |
| 54 | Assume the maximum system PID is 7 for this example. | |
| 55 | ||
| 56 | Initial whitelist: | |
| 57 | ||
| 58 | ------------------------------- | |
| 59 | [0] [1] [2] [3] [4] [5] [6] [7] | |
| 60 | ------------------------------- | |
| 61 | ||
| 62 | Command: | |
| 63 | ||
| d4f093aa | 64 | [role="term"] |
| 65226554 PP |
65 | ----------------------------------- |
| 66 | lttng track --userspace --pid=3,6,7 | |
| 67 | ----------------------------------- | |
| 68 | ||
| 69 | Whitelist: | |
| 70 | ||
| 71 | ------------------------------- | |
| 72 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
| 73 | ------------------------------- | |
| 74 | ||
| 75 | Command: | |
| 76 | ||
| d4f093aa | 77 | [role="term"] |
| 65226554 PP |
78 | --------------------------------- |
| 79 | lttng untrack --userspace --pid=7 | |
| 80 | --------------------------------- | |
| 81 | ||
| 82 | Whitelist: | |
| 83 | ||
| 84 | ------------------------------- | |
| 85 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
| 86 | ------------------------------- | |
| 87 | ||
| 88 | Command: | |
| 89 | ||
| d4f093aa | 90 | [role="term"] |
| 65226554 PP |
91 | --------------------------------- |
| 92 | lttng track --userspace --pid=1,5 | |
| 93 | --------------------------------- | |
| 94 | ||
| 95 | Whitelist: | |
| 96 | ||
| 97 | ------------------------------- | |
| 98 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
| 99 | ------------------------------- | |
| 100 | ||
| 101 | It should be noted that the PID tracker tracks the numeric process IDs. | |
| 102 | Should a process with a given ID exit and another process be given this | |
| 103 | ID, then the latter would also be allowed to emit events. | |
| 104 | ||
| 105 | See the linklttng:lttng-untrack(1) for more details about removing | |
| 106 | entries. | |
| 107 | ||
| 108 | ||
| 109 | include::common-cmd-options-head.txt[] | |
| 110 | ||
| 111 | ||
| 112 | Domain | |
| 113 | ~~~~~~ | |
| 114 | One of: | |
| 115 | ||
| 116 | option:-k, option:--kernel:: | |
| 117 | Track resources in the Linux kernel domain. | |
| 118 | ||
| 119 | option:-u, option:--userspace:: | |
| 120 | Track resources in the user space domain. | |
| 121 | ||
| 122 | ||
| 123 | Target | |
| 124 | ~~~~~~ | |
| 125 | option:-s, option:--session='SESSION':: | |
| 126 | Track resources in the tracing session named 'SESSION' instead of | |
| 127 | the current tracing session. | |
| 128 | ||
| 129 | ||
| 130 | Tracking | |
| 131 | ~~~~~~~~ | |
| 132 | option:-a, option:--all:: | |
| 133 | Used in conjunction with an empty option:--pid option: track _all_ | |
| 134 | process IDs (add all entries to the whitelist). | |
| 135 | ||
| 136 | option:-p, option:--pid[='PID'[,'PID']...]:: | |
| 137 | Track process IDs 'PID' (add them to the current whitelist). | |
| 138 | + | |
| 139 | The 'PID' argument must be omitted when also using the option:--all | |
| 140 | option. | |
| 141 | ||
| 142 | ||
| 143 | include::common-cmd-help-options.txt[] | |
| 144 | ||
| 145 | ||
| 146 | include::common-cmd-footer.txt[] | |
| 147 | ||
| 148 | ||
| 149 | SEE ALSO | |
| 150 | -------- | |
| 151 | linklttng:lttng-untrack(1), | |
| 152 | linklttng:lttng(1) |