Commit | Line | Data |
---|---|---|
307a8468 PP |
1 | lttng(1) |
2 | ======== | |
4605890e | 3 | :revdate: 16 October 2019 |
307a8468 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
5d231d82 | 8 | lttng - LTTng 2 tracer control command-line tool |
307a8468 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
5d231d82 PP |
13 | [verse] |
14 | *lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH'] | |
790e4a4c | 15 | [option:--quiet | option:-v | option:-vv | option:-vvv] '<<commands,COMMAND>>' ['COMMAND OPTIONS'] |
307a8468 PP |
16 | |
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
a18d9544 | 20 | The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open |
5d231d82 PP |
21 | source software package used for correlated tracing of the Linux kernel, |
22 | user applications, and user libraries. | |
307a8468 | 23 | |
5d231d82 PP |
24 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and |
25 | dynamically loaded libraries (for user application and library tracing). | |
307a8468 | 26 | |
7c1a4458 | 27 | An LTTng _session daemon_, man:lttng-sessiond(8), receives |
5d231d82 PP |
28 | commands from the command-line interface `lttng` to control the LTTng |
29 | tracers. All interactions with the LTTng tracers happen through the | |
30 | `lttng` tool or through the liblttng-ctl library shipped with the | |
31 | LTTng-tools package. | |
307a8468 | 32 | |
5d231d82 PP |
33 | A _tracing domain_ is a tracer category. There are five available |
34 | domains. For some commands, the domain needs to be specified with a | |
35 | command-line option. The domain options are: | |
307a8468 | 36 | |
b5217c86 | 37 | nloption:-j, nloption:--jul:: |
5d231d82 | 38 | Apply command to the `java.util.logging` (JUL) domain. |
307a8468 | 39 | |
b5217c86 | 40 | nloption:-k, nloption:--kernel:: |
5d231d82 | 41 | Apply command to the Linux kernel domain. |
307a8468 | 42 | |
b5217c86 | 43 | nloption:-l, nloption:--log4j:: |
edb4fc87 PP |
44 | Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2] |
45 | (Java) domain. | |
307a8468 | 46 | |
b5217c86 | 47 | nloption:-p, nloption:--python:: |
edb4fc87 | 48 | Apply command to the https://www.python.org/[Python] domain. |
307a8468 | 49 | |
b5217c86 | 50 | nloption:-u, nloption:--userspace:: |
edb4fc87 | 51 | Apply command to the user space domain (application using |
7c1a4458 | 52 | liblttng-ust directly; see man:lttng-ust(3)). |
307a8468 | 53 | |
5d231d82 PP |
54 | The LTTng session daemon is a tracing registry which allows the user to |
55 | interact with multiple tracers (kernel and user space) within the same | |
56 | container, a _tracing session_. Traces can be gathered from the Linux | |
57 | kernel and/or from instrumented applications (see | |
7c1a4458 PP |
58 | man:lttng-ust(3)). You can aggregate and read the events of LTTng |
59 | traces using man:babeltrace(1). | |
307a8468 | 60 | |
5d231d82 PP |
61 | To trace the Linux kernel, the session daemon needs to be running as |
62 | `root`. LTTng uses a _tracing group_ to allow specific users to interact | |
63 | with the root session daemon. The default tracing group name is | |
64 | `tracing`. You can use the option:--group option to set the tracing | |
65 | group name to use. | |
307a8468 | 66 | |
5d231d82 PP |
67 | Session daemons can coexist. You can have a session daemon running as |
68 | user Alice that can be used to trace her applications alongside a root | |
69 | session daemon or a session daemon running as user Bob. | |
307a8468 | 70 | |
5d231d82 PP |
71 | NOTE: It is highly recommended to start the session daemon at boot time |
72 | for stable and long-term tracing. | |
307a8468 | 73 | |
5d231d82 PP |
74 | User applications instrumented with LTTng automatically register to the |
75 | root session daemon and to user session daemons. This allows any session | |
76 | daemon to list the available traceable applications and event sources | |
7c1a4458 | 77 | (see man:lttng-list(1)). |
307a8468 | 78 | |
7c1a4458 | 79 | By default, the man:lttng-create(1) command automatically spawns a |
5d231d82 PP |
80 | user session daemon if none is currently running. The |
81 | option:--no-sessiond general option can be set to avoid this. | |
307a8468 | 82 | |
307a8468 | 83 | |
5d231d82 PP |
84 | OPTIONS |
85 | ------- | |
59b19c3c | 86 | option:-g 'GROUP', option:--group='GROUP':: |
5d231d82 | 87 | Use 'GROUP' as Unix tracing group (default: `tracing`). |
307a8468 | 88 | |
59b19c3c | 89 | option:-m 'TYPE', option:--mi='TYPE':: |
5d231d82 PP |
90 | Print the command's result using the machine interface type 'TYPE' |
91 | instead of a human-readable output. | |
92 | + | |
93 | Supported types: `xml`. | |
94 | + | |
95 | The machine interface (MI) mode converts the traditional pretty-printing | |
96 | to a machine output syntax. The MI mode provides a change-resistant way | |
97 | to access information generated by the `lttng` command-line program. | |
98 | + | |
99 | When using the MI mode, the data is printed to the standard output. | |
100 | Errors and warnings are printed on the standard error with the | |
101 | pretty-print default format. | |
102 | + | |
103 | If any error occurs during the execution of a command, the return value | |
104 | of the command will be different than 0. In this case, `lttng` does | |
105 | :not: guarantee the syntax and data validity of the generated MI output. | |
106 | + | |
107 | For the `xml` MI type, an XML schema definition (XSD) file used for | |
108 | validation is available: see the `src/common/mi_lttng.xsd` file in | |
109 | the LTTng-tools source tree. | |
307a8468 | 110 | |
5d231d82 PP |
111 | option:-n, option:--no-sessiond:: |
112 | Do not automatically spawn a session daemon. | |
307a8468 | 113 | |
5d231d82 PP |
114 | option:-q, option:--quiet:: |
115 | Suppress all messages, including warnings and errors. | |
307a8468 | 116 | |
5d231d82 PP |
117 | option:--sessiond-path='PATH':: |
118 | Set the session daemon binary's absolute path to 'PATH'. | |
307a8468 | 119 | |
5d231d82 PP |
120 | option:-v, option:--verbose:: |
121 | Increase verbosity. | |
122 | + | |
123 | Three levels of verbosity are available, which are triggered by | |
124 | appending additional `v` letters to the option | |
125 | (that is, `-vv` and `-vvv`). | |
307a8468 | 126 | |
307a8468 | 127 | |
5d231d82 PP |
128 | Program information |
129 | ~~~~~~~~~~~~~~~~~~~ | |
130 | option:-h, option:--help:: | |
131 | Show help. | |
307a8468 | 132 | |
5d231d82 PP |
133 | option:--list-commands:: |
134 | List available commands. | |
307a8468 | 135 | |
5d231d82 PP |
136 | option:--list-options:: |
137 | List available general options. | |
307a8468 | 138 | |
5d231d82 PP |
139 | option:-V, option:--version:: |
140 | Show version. | |
307a8468 | 141 | |
307a8468 | 142 | |
790e4a4c | 143 | [[commands]] |
5d231d82 PP |
144 | COMMANDS |
145 | -------- | |
b5217c86 | 146 | The following commands also have their own nloption:--help option. |
307a8468 | 147 | |
307a8468 | 148 | |
5d231d82 PP |
149 | Tracing sessions |
150 | ~~~~~~~~~~~~~~~~ | |
7c1a4458 | 151 | man:lttng-create(1):: |
61fa5028 | 152 | {cmd_descr_create}. |
307a8468 | 153 | |
7c1a4458 | 154 | man:lttng-destroy(1):: |
61fa5028 | 155 | {cmd_descr_destroy}. |
307a8468 | 156 | |
7c1a4458 | 157 | man:lttng-load(1):: |
61fa5028 | 158 | {cmd_descr_load}. |
31415f87 | 159 | |
faf04ce7 PP |
160 | man:lttng-regenerate(1):: |
161 | {cmd_descr_regenerate}. | |
162 | ||
7c1a4458 | 163 | man:lttng-save(1):: |
61fa5028 | 164 | {cmd_descr_save}. |
307a8468 | 165 | |
7c1a4458 | 166 | man:lttng-set-session(1):: |
61fa5028 | 167 | {cmd_descr_set_session}. |
307a8468 | 168 | |
307a8468 | 169 | |
5d231d82 PP |
170 | Channels |
171 | ~~~~~~~~ | |
7c1a4458 | 172 | man:lttng-add-context(1):: |
61fa5028 | 173 | {cmd_descr_add_context}. |
307a8468 | 174 | |
7c1a4458 | 175 | man:lttng-disable-channel(1):: |
61fa5028 | 176 | {cmd_descr_disable_channel}. |
307a8468 | 177 | |
7c1a4458 | 178 | man:lttng-enable-channel(1):: |
61fa5028 | 179 | {cmd_descr_enable_channel}. |
307a8468 | 180 | |
307a8468 | 181 | |
5d231d82 PP |
182 | Event rules |
183 | ~~~~~~~~~~~ | |
7c1a4458 | 184 | man:lttng-disable-event(1):: |
61fa5028 | 185 | {cmd_descr_disable_event}. |
307a8468 | 186 | |
7c1a4458 | 187 | man:lttng-enable-event(1):: |
61fa5028 | 188 | {cmd_descr_enable_event}. |
31415f87 | 189 | |
307a8468 | 190 | |
5d231d82 PP |
191 | Status |
192 | ~~~~~~ | |
7c1a4458 | 193 | man:lttng-list(1):: |
61fa5028 | 194 | {cmd_descr_list}. |
307a8468 | 195 | |
7c1a4458 | 196 | man:lttng-status(1):: |
61fa5028 | 197 | {cmd_descr_status}. |
307a8468 | 198 | |
307a8468 | 199 | |
5d231d82 PP |
200 | Control |
201 | ~~~~~~~ | |
7c1a4458 | 202 | man:lttng-snapshot(1):: |
61fa5028 | 203 | {cmd_descr_snapshot}. |
307a8468 | 204 | |
7c1a4458 | 205 | man:lttng-start(1):: |
61fa5028 | 206 | {cmd_descr_start}. |
307a8468 | 207 | |
7c1a4458 | 208 | man:lttng-stop(1):: |
61fa5028 | 209 | {cmd_descr_stop}. |
307a8468 | 210 | |
307a8468 | 211 | |
980bb5fd PP |
212 | Tracing session rotation |
213 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
214 | man:lttng-disable-rotation(1):: | |
215 | {cmd_descr_disable_rotation}. | |
216 | ||
217 | man:lttng-enable-rotation(1):: | |
218 | {cmd_descr_enable_rotation}. | |
219 | ||
220 | man:lttng-rotate(1):: | |
221 | {cmd_descr_rotate}. | |
222 | ||
223 | ||
224 | ||
5d231d82 PP |
225 | Resource tracking |
226 | ~~~~~~~~~~~~~~~~~ | |
7c1a4458 | 227 | man:lttng-track(1):: |
61fa5028 | 228 | {cmd_descr_track}. |
307a8468 | 229 | |
7c1a4458 | 230 | man:lttng-untrack(1):: |
61fa5028 | 231 | {cmd_descr_untrack}. |
307a8468 | 232 | |
307a8468 | 233 | |
5d231d82 PP |
234 | Miscellaneous |
235 | ~~~~~~~~~~~~~ | |
7c1a4458 | 236 | man:lttng-help(1):: |
61fa5028 | 237 | {cmd_descr_help}. |
307a8468 | 238 | |
7c1a4458 | 239 | man:lttng-version(1):: |
61fa5028 | 240 | {cmd_descr_version}. |
307a8468 | 241 | |
7c1a4458 | 242 | man:lttng-view(1):: |
61fa5028 | 243 | {cmd_descr_view}. |
307a8468 PP |
244 | |
245 | ||
5d231d82 | 246 | include::common-cmd-footer.txt[] |
307a8468 PP |
247 | |
248 | ||
249 | SEE ALSO | |
250 | -------- | |
7c1a4458 PP |
251 | man:lttng-sessiond(8), |
252 | man:lttng-relayd(8), | |
253 | man:lttng-crash(1), | |
254 | man:lttng-ust(3), | |
255 | man:babeltrace(1) |