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