| 1 | lttng(1) |
| 2 | ======== |
| 3 | |
| 4 | |
| 5 | NAME |
| 6 | ---- |
| 7 | lttng - LTTng 2 tracer control command-line tool |
| 8 | |
| 9 | |
| 10 | SYNOPSIS |
| 11 | -------- |
| 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'] |
| 15 | |
| 16 | |
| 17 | DESCRIPTION |
| 18 | ----------- |
| 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. |
| 22 | |
| 23 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and |
| 24 | dynamically loaded libraries (for user application and library tracing). |
| 25 | |
| 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. |
| 31 | |
| 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: |
| 35 | |
| 36 | option:-j, option:--jul:: |
| 37 | Apply command to the `java.util.logging` (JUL) domain. |
| 38 | |
| 39 | option:-k, option:--kernel:: |
| 40 | Apply command to the Linux kernel domain. |
| 41 | |
| 42 | option:-l, option:--log4j:: |
| 43 | Apply command to the Apache log4j 1.2 (Java) domain. |
| 44 | |
| 45 | option:-p, option:--python:: |
| 46 | Apply command to the Python domain. |
| 47 | |
| 48 | option:-u, option:--userspace:: |
| 49 | Apply command to the user space domain. |
| 50 | |
| 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). |
| 57 | |
| 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. |
| 63 | |
| 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. |
| 67 | |
| 68 | NOTE: It is highly recommended to start the session daemon at boot time |
| 69 | for stable and long-term tracing. |
| 70 | |
| 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)). |
| 75 | |
| 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. |
| 79 | |
| 80 | |
| 81 | OPTIONS |
| 82 | ------- |
| 83 | option:-g, option:--group='GROUP':: |
| 84 | Use 'GROUP' as Unix tracing group (default: `tracing`). |
| 85 | |
| 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. |
| 107 | |
| 108 | option:-n, option:--no-sessiond:: |
| 109 | Do not automatically spawn a session daemon. |
| 110 | |
| 111 | option:-q, option:--quiet:: |
| 112 | Suppress all messages, including warnings and errors. |
| 113 | |
| 114 | option:--sessiond-path='PATH':: |
| 115 | Set the session daemon binary's absolute path to 'PATH'. |
| 116 | |
| 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`). |
| 123 | |
| 124 | |
| 125 | Program information |
| 126 | ~~~~~~~~~~~~~~~~~~~ |
| 127 | option:-h, option:--help:: |
| 128 | Show help. |
| 129 | |
| 130 | option:--list-commands:: |
| 131 | List available commands. |
| 132 | |
| 133 | option:--list-options:: |
| 134 | List available general options. |
| 135 | |
| 136 | option:-V, option:--version:: |
| 137 | Show version. |
| 138 | |
| 139 | |
| 140 | COMMANDS |
| 141 | -------- |
| 142 | The following commands also have their own option:--help option. |
| 143 | |
| 144 | |
| 145 | Tracing sessions |
| 146 | ~~~~~~~~~~~~~~~~ |
| 147 | linklttng:lttng-create(1):: |
| 148 | Create a tracing session. |
| 149 | |
| 150 | linklttng:lttng-destroy(1):: |
| 151 | Tear down tracing sessions. |
| 152 | |
| 153 | linklttng:lttng-load(1):: |
| 154 | Load tracing session configurations. |
| 155 | |
| 156 | linklttng:lttng-metadata(1):: |
| 157 | Manage an LTTng tracing session's metadata generation. |
| 158 | |
| 159 | linklttng:lttng-save(1):: |
| 160 | Save tracing session configurations. |
| 161 | |
| 162 | linklttng:lttng-set-session(1):: |
| 163 | Set current tracing session. |
| 164 | |
| 165 | |
| 166 | Channels |
| 167 | ~~~~~~~~ |
| 168 | linklttng:lttng-add-context(1):: |
| 169 | Add context fields to a channel. |
| 170 | |
| 171 | linklttng:lttng-disable-channel(1):: |
| 172 | Disable tracing channels. |
| 173 | |
| 174 | linklttng:lttng-enable-channel(1):: |
| 175 | Create or enable tracing channels. |
| 176 | |
| 177 | |
| 178 | Event rules |
| 179 | ~~~~~~~~~~~ |
| 180 | linklttng:lttng-disable-event(1):: |
| 181 | Disable event rules. |
| 182 | |
| 183 | linklttng:lttng-enable-event(1):: |
| 184 | Create or enable event rules. |
| 185 | |
| 186 | |
| 187 | Status |
| 188 | ~~~~~~ |
| 189 | linklttng:lttng-list(1):: |
| 190 | List tracing sessions, domains, channels, and events. |
| 191 | |
| 192 | linklttng:lttng-status(1):: |
| 193 | Get the status of the current tracing session. |
| 194 | |
| 195 | |
| 196 | Control |
| 197 | ~~~~~~~ |
| 198 | linklttng:lttng-snapshot(1):: |
| 199 | Snapshot buffers of current tracing session. |
| 200 | |
| 201 | linklttng:lttng-start(1):: |
| 202 | Start tracing. |
| 203 | |
| 204 | linklttng:lttng-stop(1):: |
| 205 | Stop tracing. |
| 206 | |
| 207 | |
| 208 | Resource tracking |
| 209 | ~~~~~~~~~~~~~~~~~ |
| 210 | linklttng:lttng-track(1):: |
| 211 | Track specific system resources. |
| 212 | |
| 213 | linklttng:lttng-untrack(1):: |
| 214 | Untrack specific system resources. |
| 215 | |
| 216 | |
| 217 | Miscellaneous |
| 218 | ~~~~~~~~~~~~~ |
| 219 | linklttng:lttng-calibrate(1):: |
| 220 | Quantify LTTng overhead. |
| 221 | |
| 222 | linklttng:lttng-help(1):: |
| 223 | Display help information about a command. |
| 224 | |
| 225 | linklttng:lttng-version(1):: |
| 226 | Show version information. |
| 227 | |
| 228 | linklttng:lttng-view(1):: |
| 229 | Start trace viewer. |
| 230 | |
| 231 | |
| 232 | include::common-cmd-footer.txt[] |
| 233 | |
| 234 | |
| 235 | SEE ALSO |
| 236 | -------- |
| 237 | linklttng:lttng-sessiond(8), |
| 238 | linklttng:lttng-relayd(8), |
| 239 | linklttng:lttng-crash(1), |
| 240 | linklttng:lttng-ust(3), |
| 241 | linklttng:babeltrace(1) |