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