| 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] '<<commands,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_, man: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 | nloption:-j, nloption:--jul:: |
| 37 | Apply command to the `java.util.logging` (JUL) domain. |
| 38 | |
| 39 | nloption:-k, nloption:--kernel:: |
| 40 | Apply command to the Linux kernel domain. |
| 41 | |
| 42 | nloption:-l, nloption:--log4j:: |
| 43 | Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2] |
| 44 | (Java) domain. |
| 45 | |
| 46 | nloption:-p, nloption:--python:: |
| 47 | Apply command to the https://www.python.org/[Python] domain. |
| 48 | |
| 49 | nloption:-u, nloption:--userspace:: |
| 50 | Apply command to the user space domain (application using |
| 51 | liblttng-ust directly; see man:lttng-ust(3)). |
| 52 | |
| 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 | man:lttng-ust(3)). You can aggregate and read the events of LTTng |
| 58 | traces using man:babeltrace(1). |
| 59 | |
| 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. |
| 65 | |
| 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. |
| 69 | |
| 70 | NOTE: It is highly recommended to start the session daemon at boot time |
| 71 | for stable and long-term tracing. |
| 72 | |
| 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 man:lttng-list(1)). |
| 77 | |
| 78 | By default, the man: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. |
| 81 | |
| 82 | |
| 83 | OPTIONS |
| 84 | ------- |
| 85 | option:-g, option:--group='GROUP':: |
| 86 | Use 'GROUP' as Unix tracing group (default: `tracing`). |
| 87 | |
| 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. |
| 109 | |
| 110 | option:-n, option:--no-sessiond:: |
| 111 | Do not automatically spawn a session daemon. |
| 112 | |
| 113 | option:-q, option:--quiet:: |
| 114 | Suppress all messages, including warnings and errors. |
| 115 | |
| 116 | option:--sessiond-path='PATH':: |
| 117 | Set the session daemon binary's absolute path to 'PATH'. |
| 118 | |
| 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`). |
| 125 | |
| 126 | |
| 127 | Program information |
| 128 | ~~~~~~~~~~~~~~~~~~~ |
| 129 | option:-h, option:--help:: |
| 130 | Show help. |
| 131 | |
| 132 | option:--list-commands:: |
| 133 | List available commands. |
| 134 | |
| 135 | option:--list-options:: |
| 136 | List available general options. |
| 137 | |
| 138 | option:-V, option:--version:: |
| 139 | Show version. |
| 140 | |
| 141 | |
| 142 | [[commands]] |
| 143 | COMMANDS |
| 144 | -------- |
| 145 | The following commands also have their own nloption:--help option. |
| 146 | |
| 147 | |
| 148 | Tracing sessions |
| 149 | ~~~~~~~~~~~~~~~~ |
| 150 | man:lttng-create(1):: |
| 151 | {cmd_descr_create}. |
| 152 | |
| 153 | man:lttng-destroy(1):: |
| 154 | {cmd_descr_destroy}. |
| 155 | |
| 156 | man:lttng-load(1):: |
| 157 | {cmd_descr_load}. |
| 158 | |
| 159 | man:lttng-metadata(1):: |
| 160 | {cmd_descr_metadata}. |
| 161 | |
| 162 | man:lttng-save(1):: |
| 163 | {cmd_descr_save}. |
| 164 | |
| 165 | man:lttng-set-session(1):: |
| 166 | {cmd_descr_set_session}. |
| 167 | |
| 168 | |
| 169 | Channels |
| 170 | ~~~~~~~~ |
| 171 | man:lttng-add-context(1):: |
| 172 | {cmd_descr_add_context}. |
| 173 | |
| 174 | man:lttng-disable-channel(1):: |
| 175 | {cmd_descr_disable_channel}. |
| 176 | |
| 177 | man:lttng-enable-channel(1):: |
| 178 | {cmd_descr_enable_channel}. |
| 179 | |
| 180 | |
| 181 | Event rules |
| 182 | ~~~~~~~~~~~ |
| 183 | man:lttng-disable-event(1):: |
| 184 | {cmd_descr_disable_event}. |
| 185 | |
| 186 | man:lttng-enable-event(1):: |
| 187 | {cmd_descr_enable_event}. |
| 188 | |
| 189 | |
| 190 | Status |
| 191 | ~~~~~~ |
| 192 | man:lttng-list(1):: |
| 193 | {cmd_descr_list}. |
| 194 | |
| 195 | man:lttng-status(1):: |
| 196 | {cmd_descr_status}. |
| 197 | |
| 198 | |
| 199 | Control |
| 200 | ~~~~~~~ |
| 201 | man:lttng-snapshot(1):: |
| 202 | {cmd_descr_snapshot}. |
| 203 | |
| 204 | man:lttng-start(1):: |
| 205 | {cmd_descr_start}. |
| 206 | |
| 207 | man:lttng-stop(1):: |
| 208 | {cmd_descr_stop}. |
| 209 | |
| 210 | |
| 211 | Resource tracking |
| 212 | ~~~~~~~~~~~~~~~~~ |
| 213 | man:lttng-track(1):: |
| 214 | {cmd_descr_track}. |
| 215 | |
| 216 | man:lttng-untrack(1):: |
| 217 | {cmd_descr_untrack}. |
| 218 | |
| 219 | |
| 220 | Miscellaneous |
| 221 | ~~~~~~~~~~~~~ |
| 222 | man:lttng-calibrate(1):: |
| 223 | {cmd_descr_calibrate}. |
| 224 | |
| 225 | man:lttng-help(1):: |
| 226 | {cmd_descr_help}. |
| 227 | |
| 228 | man:lttng-version(1):: |
| 229 | {cmd_descr_version}. |
| 230 | |
| 231 | man:lttng-view(1):: |
| 232 | {cmd_descr_view}. |
| 233 | |
| 234 | |
| 235 | include::common-cmd-footer.txt[] |
| 236 | |
| 237 | |
| 238 | SEE ALSO |
| 239 | -------- |
| 240 | man:lttng-sessiond(8), |
| 241 | man:lttng-relayd(8), |
| 242 | man:lttng-crash(1), |
| 243 | man:lttng-ust(3), |
| 244 | man:babeltrace(1) |