| 1 | lttng(1) |
| 2 | ======== |
| 3 | :revdate: 16 October 2019 |
| 4 | |
| 5 | |
| 6 | NAME |
| 7 | ---- |
| 8 | lttng - LTTng 2 tracer control command-line tool |
| 9 | |
| 10 | |
| 11 | SYNOPSIS |
| 12 | -------- |
| 13 | [verse] |
| 14 | *lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH'] |
| 15 | [option:--quiet | option:-v | option:-vv | option:-vvv] '<<commands,COMMAND>>' ['COMMAND OPTIONS'] |
| 16 | |
| 17 | |
| 18 | DESCRIPTION |
| 19 | ----------- |
| 20 | The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open |
| 21 | source software package used for correlated tracing of the Linux kernel, |
| 22 | user applications, and user libraries. |
| 23 | |
| 24 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and |
| 25 | dynamically loaded libraries (for user application and library tracing). |
| 26 | |
| 27 | An LTTng _session daemon_, man:lttng-sessiond(8), receives |
| 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. |
| 32 | |
| 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: |
| 36 | |
| 37 | nloption:-j, nloption:--jul:: |
| 38 | Apply command to the `java.util.logging` (JUL) domain. |
| 39 | |
| 40 | nloption:-k, nloption:--kernel:: |
| 41 | Apply command to the Linux kernel domain. |
| 42 | |
| 43 | nloption:-l, nloption:--log4j:: |
| 44 | Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2] |
| 45 | (Java) domain. |
| 46 | |
| 47 | nloption:-p, nloption:--python:: |
| 48 | Apply command to the https://www.python.org/[Python] domain. |
| 49 | |
| 50 | nloption:-u, nloption:--userspace:: |
| 51 | Apply command to the user space domain (application using |
| 52 | liblttng-ust directly; see man:lttng-ust(3)). |
| 53 | |
| 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 |
| 58 | man:lttng-ust(3)). You can aggregate and read the events of LTTng |
| 59 | traces using man:babeltrace(1). |
| 60 | |
| 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. |
| 66 | |
| 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. |
| 70 | |
| 71 | NOTE: It is highly recommended to start the session daemon at boot time |
| 72 | for stable and long-term tracing. |
| 73 | |
| 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 |
| 77 | (see man:lttng-list(1)). |
| 78 | |
| 79 | By default, the man:lttng-create(1) command automatically spawns a |
| 80 | user session daemon if none is currently running. The |
| 81 | option:--no-sessiond general option can be set to avoid this. |
| 82 | |
| 83 | |
| 84 | OPTIONS |
| 85 | ------- |
| 86 | option:-g 'GROUP', option:--group='GROUP':: |
| 87 | Use 'GROUP' as Unix tracing group (default: `tracing`). |
| 88 | |
| 89 | option:-m 'TYPE', option:--mi='TYPE':: |
| 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. |
| 110 | |
| 111 | option:-n, option:--no-sessiond:: |
| 112 | Do not automatically spawn a session daemon. |
| 113 | |
| 114 | option:-q, option:--quiet:: |
| 115 | Suppress all messages, including warnings and errors. |
| 116 | |
| 117 | option:--sessiond-path='PATH':: |
| 118 | Set the session daemon binary's absolute path to 'PATH'. |
| 119 | |
| 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`). |
| 126 | |
| 127 | |
| 128 | Program information |
| 129 | ~~~~~~~~~~~~~~~~~~~ |
| 130 | option:-h, option:--help:: |
| 131 | Show help. |
| 132 | |
| 133 | option:--list-commands:: |
| 134 | List available commands. |
| 135 | |
| 136 | option:--list-options:: |
| 137 | List available general options. |
| 138 | |
| 139 | option:-V, option:--version:: |
| 140 | Show version. |
| 141 | |
| 142 | |
| 143 | [[commands]] |
| 144 | COMMANDS |
| 145 | -------- |
| 146 | The following commands also have their own nloption:--help option. |
| 147 | |
| 148 | |
| 149 | Tracing sessions |
| 150 | ~~~~~~~~~~~~~~~~ |
| 151 | man:lttng-create(1):: |
| 152 | {cmd_descr_create}. |
| 153 | |
| 154 | man:lttng-destroy(1):: |
| 155 | {cmd_descr_destroy}. |
| 156 | |
| 157 | man:lttng-load(1):: |
| 158 | {cmd_descr_load}. |
| 159 | |
| 160 | man:lttng-regenerate(1):: |
| 161 | {cmd_descr_regenerate}. |
| 162 | |
| 163 | man:lttng-save(1):: |
| 164 | {cmd_descr_save}. |
| 165 | |
| 166 | man:lttng-set-session(1):: |
| 167 | {cmd_descr_set_session}. |
| 168 | |
| 169 | |
| 170 | Channels |
| 171 | ~~~~~~~~ |
| 172 | man:lttng-add-context(1):: |
| 173 | {cmd_descr_add_context}. |
| 174 | |
| 175 | man:lttng-disable-channel(1):: |
| 176 | {cmd_descr_disable_channel}. |
| 177 | |
| 178 | man:lttng-enable-channel(1):: |
| 179 | {cmd_descr_enable_channel}. |
| 180 | |
| 181 | |
| 182 | Event rules |
| 183 | ~~~~~~~~~~~ |
| 184 | man:lttng-disable-event(1):: |
| 185 | {cmd_descr_disable_event}. |
| 186 | |
| 187 | man:lttng-enable-event(1):: |
| 188 | {cmd_descr_enable_event}. |
| 189 | |
| 190 | |
| 191 | Status |
| 192 | ~~~~~~ |
| 193 | man:lttng-list(1):: |
| 194 | {cmd_descr_list}. |
| 195 | |
| 196 | man:lttng-status(1):: |
| 197 | {cmd_descr_status}. |
| 198 | |
| 199 | |
| 200 | Control |
| 201 | ~~~~~~~ |
| 202 | man:lttng-snapshot(1):: |
| 203 | {cmd_descr_snapshot}. |
| 204 | |
| 205 | man:lttng-start(1):: |
| 206 | {cmd_descr_start}. |
| 207 | |
| 208 | man:lttng-stop(1):: |
| 209 | {cmd_descr_stop}. |
| 210 | |
| 211 | |
| 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 | |
| 225 | Resource tracking |
| 226 | ~~~~~~~~~~~~~~~~~ |
| 227 | man:lttng-track(1):: |
| 228 | {cmd_descr_track}. |
| 229 | |
| 230 | man:lttng-untrack(1):: |
| 231 | {cmd_descr_untrack}. |
| 232 | |
| 233 | |
| 234 | Miscellaneous |
| 235 | ~~~~~~~~~~~~~ |
| 236 | man:lttng-help(1):: |
| 237 | {cmd_descr_help}. |
| 238 | |
| 239 | man:lttng-version(1):: |
| 240 | {cmd_descr_version}. |
| 241 | |
| 242 | man:lttng-view(1):: |
| 243 | {cmd_descr_view}. |
| 244 | |
| 245 | |
| 246 | include::common-cmd-footer.txt[] |
| 247 | |
| 248 | |
| 249 | SEE ALSO |
| 250 | -------- |
| 251 | man:lttng-sessiond(8), |
| 252 | man:lttng-relayd(8), |
| 253 | man:lttng-crash(1), |
| 254 | man:lttng-ust(3), |
| 255 | man:babeltrace(1) |