+++ /dev/null
-.TH "LTTNG" "1" "May 13th, 2014" "" ""
-
-.SH "NAME"
-lttng \- LTTng 2.x tracer control command line tool
-
-.SH "SYNOPSIS"
-
-.PP
-lttng [OPTIONS] <COMMAND>
-.SH "DESCRIPTION"
-
-.PP
-The LTTng project aims at providing highly efficient tracing tools for Linux.
-Its tracers help track down performance issues and debug problems
-involving multiple concurrent processes and threads. Tracing across multiple
-systems is also possible.
-
-The \fBlttng\fP command line tool from the lttng-tools package is used to control
-both kernel and user-space tracing. Every interaction with the tracer should
-be done by this tool or by the liblttng-ctl library provided by the lttng-tools
-package.
-
-LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry,
-which allows you to interact with multiple tracers (kernel and user-space)
-inside the same container, a tracing session. Traces can be gathered from the
-kernel and/or instrumented applications (lttng-ust(3)). Aggregating and reading
-those traces is done using the babeltrace(1) text viewer.
-
-We introduce the notion of \fBtracing domains\fP which is essentially a type of
-tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
-could see more tracer like for instance an hypervisor. For some commands,
-you'll need to specify on which domain the command operates (\-u, \-k, \-l, \-j
-or \-p). For instance, the kernel domain must be specified when enabling a
-kernel event.
-
-In order to trace the kernel, the session daemon needs to be running as root.
-LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is
-in that group can interact with the root session daemon and thus trace the
-kernel. Session daemons can co-exist, meaning that you can have a session daemon
-running as Alice that can be used to trace her applications along side with a
-root daemon or even a Bob daemon. We highly recommend starting the session
-daemon at boot time for stable and long term tracing.
-
-Each user-space application instrumented with lttng-ust(3) will automatically
-register with the root session daemon and its user session daemon. This allows
-each daemon to list the available traceable applications and tracepoints at any
-given moment (See the \fBlist\fP command).
-.SH "OPTIONS"
-
-.PP
-This program follows the usual GNU command line syntax with long options starting with
-two dashes. Below is a summary of the available options.
-.PP
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-V, \-\-version"
-Show version.
-.TP
-.BR "\-v, \-\-verbose"
-Increase verbosity.
-Three levels of verbosity are available which are triggered by putting additional v to
-the option (\-vv or \-vvv)
-.TP
-.BR "\-q, \-\-quiet"
-Suppress all messages (even errors).
-.TP
-.BR "\-g, \-\-group NAME"
-Set unix tracing group name. (default: tracing)
-.TP
-.BR "\-n, \-\-no-sessiond"
-Don't automatically spawn a session daemon.
-.TP
-.BR "\-\-sessiond\-path PATH"
-Set session daemon full binary path.
-.TP
-.BR "\-\-list\-options"
-Simple listing of lttng options.
-.TP
-.BR "\-\-list\-commands"
-Simple listing of lttng commands.
-.TP
-.BR "\-m, \-\-mi TYPE
-Machine interface
-
-TYPE supported: XML
-
-Machine interface (MI) mode converts the traditional pretty printing to a
-machine output syntax. MI mode provides a format change-resistant way to access
-information generated via the lttng command line.
-
-When using MI mode, the data is printed on \fBstdout\fP. Error and warning are
-printed on \fBstderr\fP with the pretty print default format.
-
-If any errors occur during the execution of a command, the return value of the
-command will be different than zero. In this case, lttng does NOT guarantee the
-syntax and data validity of the generated MI output.
-
-For XML output type, a schema definition (XSD) file used for validation can be
-found under src/common/mi_lttng.xsd
-
-.SH "COMMANDS"
-
-.PP
-\fBadd-context\fP [OPTIONS]
-.RS
-Add context to event(s) and/or channel(s).
-
-A context is basically extra information appended to a channel. For instance,
-you could ask the tracer to add the PID information for all events in a
-channel. You can also add performance monitoring unit counters (perf PMU) using
-the perf kernel API.
-
-For example, this command will add the context information 'prio' and two per-CPU
-perf counters (hardware branch misses and cache misses), to all events in the trace
-data output:
-
-.nf
-# lttng add-context \-k \-t prio \-t perf:cpu:branch-misses \\
- \-t perf:cpu:cache-misses
-.fi
-
-Please take a look at the help (\-h/\-\-help) for a detailed list of available
-contexts.
-
-Perf counters are available as per-CPU ("perf:cpu:...") and per-thread
-("perf:thread:...") counters. Currently, per-CPU counters can only be
-used with the kernel tracing domain, and per-thread counters can only be
-used with the UST tracing domain.
-
-If no channel is given (\-c), the context is added to all channels that were
-already enabled. If the session has no channel, a default channel is created.
-Otherwise the context will be added only to the given channel (\-c).
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name.
-.TP
-.BR "\-c, \-\-channel NAME"
-Apply on channel name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-t, \-\-type TYPE"
-Context type. You can repeat this option on the command line. Please
-use "lttng add-context \-h" to list all available types.
-.RE
-.PP
-
-.PP
-\fBcalibrate\fP [OPTIONS]
-.RS
-Quantify LTTng overhead
-
-The LTTng calibrate command can be used to find out the combined average
-overhead of the LTTng tracer and the instrumentation mechanisms used. This
-overhead can be calibrated in terms of time or using any of the PMU performance
-counter available on the system.
-
-For now, the only calibration implemented is that of the kernel function
-instrumentation (kretprobes).
-
-* Calibrate kernel function instrumentation
-
-Let's use an example to show this calibration. We use an i7 processor with 4
-general-purpose PMU registers. This information is available by issuing dmesg,
-looking for "generic registers".
-
-This sequence of commands will gather a trace executing a kretprobe hooked on
-an empty function, gathering PMU counters LLC (Last Level Cache) misses
-information (see lttng add-context \-\-help to see the list of available PMU
-counters).
-
-.nf
-# lttng create calibrate-function
-# lttng enable-event calibrate \-\-kernel \\
- \-\-function lttng_calibrate_kretprobe
-# lttng add-context \-\-kernel \-t perf:cpu:LLC-load-misses \\
- \-t perf:cpu:LLC-store-misses \\
- \-t perf:cpu:LLC-prefetch-misses
-# lttng start
-# for a in $(seq 1 10); do \\
- lttng calibrate \-\-kernel \-\-function;
- done
-# lttng destroy
-# babeltrace $(ls \-1drt ~/lttng-traces/calibrate-function-* \\
- | tail \-n 1)
-.fi
-
-The output from babeltrace can be saved to a text file and opened in a
-spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between
-consecutive "calibrate_entry" and "calibrate_return" events. Note that these
-counters are per-CPU, so scheduling events would need to be present to account
-for migration between CPU. Therefore, for calibration purposes, only events
-staying on the same CPU must be considered.
-
-The average result, for the i7, on 10 samples:
-
-.nf
- Average Std.Dev.
-perf_LLC_load_misses: 5.0 0.577
-perf_LLC_store_misses: 1.6 0.516
-perf_LLC_prefetch_misses: 9.0 14.742
-.fi
-
-As we can notice, the load and store misses are relatively stable across runs
-(their standard deviation is relatively low) compared to the prefetch misses.
-We can conclude from this information that LLC load and store misses can be
-accounted for quite precisely, but prefetches within a function seems to behave
-too erratically (not much causality link between the code executed and the CPU
-prefetch activity) to be accounted for.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-\-function"
-Dynamic function entry/return probe (default)
-.RE
-.PP
-
-.PP
-\fBcreate\fP [NAME] [OPTIONS]
-.RS
-Create tracing session.
-
-A tracing session contains channel(s) which contains event(s). It is domain
-agnostic, meaning that channels and events can be enabled for the
-user-space tracer and/or the kernel tracer. It acts like a container
-aggregating multiple tracing sources.
-
-On creation, a \fB.lttngrc\fP file is created in your $HOME directory
-containing the current session name. If NAME is omitted, a session name is
-automatically created having this form: 'auto-yyyymmdd-hhmmss'.
-
-If no \fB\-o, \-\-output\fP is specified, the traces will be written in
-$HOME/lttng-traces.
-
-The $HOME environment variable can be overridden by defining the environment
-variable LTTNG_HOME. This is useful when the user running the commands has
-a non-writeable home directory.
-
-The session name MUST NOT contain the character '/'.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-o, \-\-output PATH"
-Specify output path for traces
-.TP
-.BR "\-\-no-output"
-Traces will not be output
-.TP
-.BR "\-\-snapshot"
-Set the session in snapshot mode. Created in no-output mode and uses the
-URL, if one is specified, as the default snapshot output. Every channel will be set
-in overwrite mode and with mmap output (splice not supported).
-.TP
-.BR "\-\-live [USEC]"
-Set the session exclusively in live mode. The parameter is the delay in micro
-seconds before the data is flushed and streamed. The live mode allows you to
-stream the trace and view it while it's being recorded by any tracer. For that,
-you need a lttng-relayd and this session requires a network URL (\-U or
-\-C/\-D). If no USEC nor URL is provided, the default is to use a timer value
-set to 1000000 and the network URL set to net://127.0.0.1.
-
-To read a live session, you can use babeltrace(1) or the live streaming
-protocol in doc/live-reading-protocol.txt. Here is an example:
-
-.nf
-$ lttng-relayd -o /tmp/lttng
-$ lttng create --live 200000 -U net://localhost
-$ lttng enable-event -a --userspace
-$ lttng start
-.fi
-
-After the start, you'll be able to read the events while they are being
-recorded in /tmp/lttng.
-
-.TP
-.BR "\-\-shm-path PATH"
-
-Path where shared memory holding buffers should be created. Useful
-when used with PRAMFS or other persistent memory filesystems to extract
-trace data in the event of a crash requiring a reboot.
-
-See the \fBlttng-crash(1)\fP utility for more information on crash recovery.
-
-.TP
-.BR "\-U, \-\-set-url=URL"
-Set URL for the consumer output destination. It is persistent for the
-session lifetime. Redo the command to change it. This will set both data
-and control URL for network.
-.TP
-.BR "\-C, \-\-ctrl-url=URL"
-Set control path URL. (Must use -D also)
-.TP
-.BR "\-D, \-\-data-url=URL"
-Set data path URL. (Must use -C also)
-.PP
-Using these options, each API call can be controlled individually. For
-instance, \-C does not enable the consumer automatically. You'll need the \-e
-option for that.
-
-.B URL FORMAT:
-
-proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
-
-Supported protocols are (proto):
-.TP
-.BR "file://..."
-Local filesystem full path.
-
-.TP
-.BR "net://..."
-This will use the default network transport layer which is TCP for both
-control (PORT1) and data port (PORT2). The default ports are
-respectively 5342 and 5343. Note that net[6]:// is not yet supported.
-
-.TP
-.BR "tcp[6]://..."
-Can only be used with -C and -D together
-
-NOTE: IPv6 address MUST be enclosed in brackets '[]' (rfc2732)
-
-.B EXAMPLES:
-
-.nf
-# lttng create -U net://192.168.1.42
-.fi
-Uses TCP and default ports for the given destination.
-
-.nf
-# lttng create -U net6://[fe80::f66d:4ff:fe53:d220]
-.fi
-Uses TCP, default ports and IPv6.
-
-.nf
-# lttng create s1 -U net://myhost.com:3229
-.fi
-Create session s1 and set its consumer to myhost.com on port 3229 for control.
-.RE
-.PP
-
-.PP
-\fBdestroy\fP [NAME] [OPTIONS]
-.RS
-Teardown tracing session
-
-Free memory on the session daemon and tracer side. It's gone!
-
-If NAME is omitted, the session name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Destroy all sessions
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBenable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
-.RS
-Enable tracing channel
-
-To enable an event, you must enable both the event and the channel that
-contains it.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-Exactly one of \-k or -u must be specified.
-
-It is important to note that if a certain type of buffers is used, the session
-will be set with that type and all other subsequent channel needs to have the
-same type.
-
-Note that once the session has been started and enabled on the tracer side,
-it's not possible anymore to enable a new channel for that session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show this help
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user-space tracer
-.TP
-.BR "\-\-discard"
-Discard event when subbuffers are full (default)
-.TP
-.BR "\-\-overwrite"
-Flight recorder mode: overwrites events when subbuffers are full. The
-number of subbuffer must be 2 or more.
-.TP
-.BR "\-\-subbuf-size SIZE"
-Subbuffer size in bytes {+k,+M,+G}.
-(default UST uid: 131072, UST pid: 4096, kernel: 262144, metadata: 4096)
-Rounded up to the next power of 2.
-
-The minimum subbuffer size, for each tracer, is the max value between
-the default above and the system page size. You can issue this command
-to get the current page size on your system: \fB$ getconf PAGE_SIZE\fP
-.TP
-.BR "\-\-num-subbuf NUM"
-Number of subbuffers. (default UST uid: 4, UST pid: 4, kernel: 4,
-metadata: 2) Rounded up to the next power of 2.
-.TP
-.BR "\-\-switch-timer USEC"
-Switch subbuffer timer interval in µsec.
-(default UST uid: 0, UST pid: 0, kernel: 0, metadata: 0)
-.TP
-.BR "\-\-read-timer USEC"
-Read timer interval in µsec.
-(default UST uid: 0, UST pid: 0, kernel: 200000, metadata: 0)
-.TP
-.BR "\-\-output TYPE"
-Channel output type. Possible values: mmap, splice
-(default UST uid: mmap, UST pid: mmap, kernel: splice, metadata: mmap)
-.TP
-.BR "\-\-buffers-uid"
-Use per UID buffer (\-u only). Buffers are shared between applications
-that have the same UID.
-.TP
-.BR "\-\-buffers-pid"
-Use per PID buffer (\-u only). Each application has its own buffers.
-.TP
-.BR "\-\-buffers-global"
-Use shared buffer for the whole system (\-k only)
-.TP
-.BR "\-C, \-\-tracefile-size SIZE"
-Maximum size of each tracefile within a stream (in bytes).
-0 means unlimited. (default: 0)
-Note: traces generated with this option may inaccurately report
-discarded events as of CTF 1.8.
-.TP
-.BR "\-W, \-\-tracefile-count COUNT"
-Used in conjunction with \-C option, this will limit the number of files
-created to the specified count. 0 means unlimited. (default: 0)
-
-.B EXAMPLES:
-
-.nf
-$ lttng enable-channel -k -C 4096 -W 32 chan1
-.fi
-For each stream, the maximum size of each trace file will be 4096 bytes and
-there will be a maximum of 32 different files. The file count is appended after
-the stream number as seen in the following example. The last trace file is
-smaller than 4096 since it was not completely filled.
-
-.nf
- ~/lttng-traces/[...]/chan1_0_0 (4096)
- ~/lttng-traces/[...]/chan1_0_1 (4096)
- ~/lttng-traces/[...]/chan1_0_2 (3245)
- ~/lttng-traces/[...]/chan1_1_0 (4096)
- ...
-.fi
-
-.nf
-$ lttng enable-channel -k -C 4096
-.fi
-This will create trace files of 4096 bytes and will create new ones as long as
-there is data available.
-.RE
-.PP
-
-.PP
-\fBenable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [OPTIONS]
-.RS
-Enable tracing event
-
-A tracing event is always assigned to a channel. If \fB\-c, \-\-channel\fP is
-omitted, a default channel named '\fBchannel0\fP' is created and the event is
-added to it. If \fB\-c, \-\-channel\fP is omitted, but a non-default
-channel already exists within the session, an error is returned. For the
-user-space tracer, using \fB\-a, \-\-all\fP is the same as using the
-wildcard "*".
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name
-.TP
-.BR "\-c, \-\-channel NAME"
-Apply on channel name
-.TP
-.BR "\-a, \-\-all"
-Enable all tracepoints and syscalls. This actually enables a single
-wildcard event "*".
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-j, \-\-jul"
-Apply for Java application using Java Util Logging interface (JUL)
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module.
-.TP
-.BR "\-\-tracepoint"
-Tracepoint event (default). Userspace tracer supports wildcards at the end
-of string. Don't forget to quote to deal with bash expansion.
-e.g.:
-.nf
- "*"
- "app_component:na*"
-.fi
-.TP
-.BR "\-\-loglevel NAME"
-Tracepoint loglevel range from 0 to loglevel. Listed in the help (\-h).
-For the JUL domain, the loglevel ranges are detailed with the \-\-help
-option thus starting from SEVERE to FINEST.
-For the LOG4J domain, loglevels range from FATAL to TRACE which are also
-detailed in the help.
-For the Python domain, loglevels range from CRITICAL to DEBUG which are
-detailed in the help as well.
-.TP
-.BR "\-\-loglevel-only NAME"
-Tracepoint loglevel (only this loglevel).
-The loglevel or loglevel-only options should be combined with a
-tracepoint name or tracepoint wildcard.
-.TP
-.BR "\-\-probe (addr | symbol | symbol+offset)"
-Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...)
-or hexadecimal (0xNNN...)
-.TP
-.BR "\-\-function (addr | symbol | symbol+offset)"
-Dynamic function entry/return probe. Addr and offset can be octal
-(0NNN...), decimal (NNN...) or hexadecimal (0xNNN...)
-.TP
-.BR "\-\-syscall"
-System call event.
-.TP
-.BR "\-\-filter 'expression'"
-Set a filter on a newly enabled event. Filter expression on event
-fields and context. The event will be recorded if the filter's
-expression evaluates to TRUE. Only specify on first activation of a
-given event within a session.
-Specifying a filter is only allowed when enabling events within a session before
-tracing is started. If the filter fails to link with the event
-within the traced domain, the event will be discarded.
-
-Expression examples:
-
-.nf
- 'intfield > 500 && intfield < 503'
- '(strfield == "test" || intfield != 10) && intfield > 33'
- 'doublefield > 1.1 && intfield < 5.3'
- 'enumfield == 1234'
-.fi
-
-Wildcards are allowed at the end of strings:
- 'seqfield1 == "te*"'
-In string literals, the escape character is a '\\'. Use '\\*' for
-the '*' character, and '\\\\' for the '\\' character sequence. Wildcard
-matches any sequence of characters, including an empty sub-string
-(matches 0 or more characters). Enumeration fields can currently only be
-compared as integers.
-
-Context information can be used for filtering. The examples below shows
-usage of context filtering on the process name (using a wildcard), process ID
-range, and unique thread ID. The process and thread IDs of
-running applications can be found under columns "PID" and "LWP" of the
-"ps -eLf" command.
-
-.nf
- '$ctx.procname == "demo*"'
- '$ctx.vpid >= 4433 && $ctx.vpid < 4455'
- '$ctx.vtid == 1234'
-.fi
-
-Context information is available to all filters whether or not the add-context
-command has been used to add it to the event's channel, as long as the context
-field exists for that domain. For example, the filter examples given above will
-never fail to link: no add-context is required for the event's channel.
-
-.TP
-.BR "\-x, \-\-exclude LIST"
-Add exclusions to UST tracepoints:
-Events that match any of the items in the comma-separated LIST are not
-enabled, even if they match a wildcard definition of the event.
-
-This option is also applicable with the \fB\-a, \-\-all\fP option,
-in which case all UST tracepoints are enabled except the ones whose
-names match any of the items in LIST.
-.RE
-.PP
-
-.PP
-\fBdisable-channel\fP NAME[,NAME2,...] (\-k | \-u) [OPTIONS]
-.RS
-Disable tracing channel
-
-Disabling a channel disables the tracing of all of the channel's events. A channel
-can be re-enabled by calling \fBlttng enable-channel NAME\fP again.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.RE
-.PP
-
-.PP
-\fBdisable-event\fP NAME[,NAME2,...] (\-k | \-u | \-j | \-l | \-p) [TYPE] [OPTIONS]
-.RS
-Disable tracing event
-
-The event, once disabled, can be re-enabled by calling \fBlttng enable-event
-NAME\fP again.
-
-If \fB\-s, \-\-session\fP is omitted, the session name is taken from the .lttngrc
-file.
-
-If \fB\-c, \-\-channel\fP is omitted, the default channel name is used.
-If \fB\-c, \-\-channel\fP is omitted, but a non-default channel already
-exists within the session, an error is returned.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-s, \-\-session NAME"
-Apply on session name
-.TP
-.BR "\-c, \-\-channel NAME"
-Apply on channel name
-.TP
-.BR "\-a, \-\-all-events"
-Disable all events. This does NOT ONLY disable "*" but rather every known
-events of the session
-.TP
-.BR "\-k, \-\-kernel"
-Apply for the kernel tracer
-.TP
-.BR "\-u, \-\-userspace"
-Apply for the user-space tracer
-.TP
-.BR "\-j, \-\-jul"
-Apply for Java application using Java Util Logging interface (JUL)
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module
-
-.TP
-.B TYPE (kernel domain only):
-
-.TP
-.BR "\-\-all"
-Disable event of all type
-.TP
-.BR "\-\-tracepoint"
-Disable event of type tracepoint
-.TP
-.BR "\-\-syscall"
-Disable event of type syscall
-.TP
-.BR "\-\-probe"
-Disable event of type probe
-.TP
-.BR "\-\-function"
-Disable event of type function
-.RE
-.PP
-
-.PP
-\fBlist\fP [OPTIONS] [SESSION [SESSION OPTIONS]]
-.RS
-List tracing session information.
-
-With no arguments, it will list available tracing session(s).
-
-With the session name, it will display the details of the session including
-the trace file path, the associated channels and their state (activated
-and deactivated), the activated events and more.
-
-With \-k alone, it will list all available kernel events (except the system
-calls events).
-With \-j alone, the available JUL event from registered application will be
-list. The event corresponds to the Logger name in the Java JUL application.
-With \-l alone, the available LOG4J event from registered application will be
-list. The event corresponds to the Logger name in the Java LOG4J application.
-With \-p alone, the available Python event from registered application will be
-list. The event corresponds to the Logger name in the Python application.
-With \-u alone, it will list all available user-space events from registered
-applications. Here is an example of 'lttng list \-u':
-
-.nf
-PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello
- ust_tests_hello:tptest_sighandler (type: tracepoint)
- ust_tests_hello:tptest (type: tracepoint)
-.fi
-
-You can now enable any event listed by using the name :
-\fBust_tests_hello:tptest\fP.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-k, \-\-kernel"
-Select kernel domain
-.TP
-.BR "\-u, \-\-userspace"
-Select user-space domain.
-.TP
-.BR "\-j, \-\-jul"
-Apply for Java application using JUL
-.TP
-.BR "\-l, \-\-log4j"
-Apply for Java application using LOG4J
-.TP
-.BR "\-p, \-\-python"
-Apply for Python application using the logging module.
-.TP
-.BR "\-f, \-\-fields"
-List event fields
-
-.PP
-.B SESSION OPTIONS:
-
-.TP
-.BR "\-c, \-\-channel NAME"
-List details of a channel
-.TP
-.BR "\-d, \-\-domain"
-List available domain(s)
-.RE
-.PP
-
-.PP
-\fBload\fP [OPTIONS] [NAME]
-.RS
-Load tracing session configuration
-
-If NAME is omitted, all session configurations found in both the user's session
-configuration directory (default: ~/.lttng/sessions/) and the system session
-configuration directory (default: /etc/lttng/sessions/) will be loaded. Note
-that the sessions in the user directory are loaded first and then the system
-wide directory are loaded.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Load all session configurations (default).
-.TP
-.BR "\-i, \-\-input-path PATH"
-Specify the input path for session configurations. This overrides the default
-session configuration directory.
-.TP
-.BR "\-f, -\-force"
-Overwrite current session configuration(s) if a session of the same name
-already exists.
-.RE
-.PP
-
-.PP
-\fBmetadata\fP [OPTIONS] ACTION
-.RS
-Metadata command for a LTTng session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-
-.PP
-.B ACTION:
-
-.TP
-\fBregenerate\fP [-s <NAME>]
-Regenerate the metadata of a session. This allows the user to regenerate the
-metadata after a major NTP correction and that way update the clock offset from
-epoch in the metadata. Only works on kernel, UST per-uid and non-live sessions.
-.RE
-.PP
-
-.PP
-\fBsave\fP [OPTIONS] [SESSION]
-.RS
-Save tracing session configuration
-
-If SESSION is omitted, all session configurations will be saved to individual
-\fB.lttng\fP files under the user's session configuration directory (default:
-~/.lttng/sessions/). The default session configuration file naming scheme is
-\fBSESSION.lttng\fP.
-
-For instance, a user in the tracing group saving a session from a root session
-daemon will save it in her/his user directory.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-a, \-\-all"
-Save all session configurations (default).
-.TP
-.BR "\-o, \-\-output-path PATH"
-Specify the output path for saved sessions. This overrides the default session
-configuration directory.
-.TP
-.BR "\-f, -\-force"
-Overwrite session configuration file if session name clashes.
-.RE
-.PP
-
-.PP
-\fBset-session\fP NAME [OPTIONS]
-.RS
-Set current session name
-
-Will change the session name in the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBsnapshot\fP [OPTIONS] ACTION
-.RS
-Snapshot command for LTTng session.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-
-.PP
-.B ACTION:
-
-.TP
-\fBadd-output\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] <URL> | -C <URL> -D <URL>
-
-Setup and add a snapshot output for a session. Output is the destination
-where the snapshot will be sent. Only one output is permitted. To change it,
-you'll need to delete it and add back the new one.
-
-.TP
-\fBdel-output\fP ID | NAME [-s <NAME>]
-
-Delete an output for a session using the output's ID. You can either specify the
-output by name or use its ID as returned by the list-output command.
-
-.TP
-\fBlist-output\fP [-s <NAME>]
-
-List the output of a session. Attributes of the output are printed.
-
-.TP
-\fBrecord\fP [-m <SIZE>] [-s <NAME>] [-n <NAME>] [<URL> | -C <URL> -D <URL>]
-
-Snapshot a session's buffer(s) for all domains. If an URL is specified, it is
-used instead of a previously added output. Specifying only a name or/and a max
-size will override the current output values. For instance, you can record a
-snapshot with a custom maximum size or with a different name.
-
-.nf
-$ lttng snapshot add-output -n mysnapshot file:///data/snapshot
-[...]
-$ lttng snapshot record -n new_name_snapshot
-.fi
-
-The above will create a snapshot in /data/snapshot/new_name_snapshot* directory
-rather then in mysnapshot*/
-
-.PP
-.B DETAILED ACTION OPTIONS
-
-.TP
-.BR "\-s, \-\-session NAME"
-Apply to session name.
-.TP
-.BR "\-n, \-\-name NAME"
-Name of the snapshot's output.
-.TP
-.BR "\-m, \-\-max-size SIZE"
-Maximum size in bytes of the snapshot. The maximum size does not include the
-metadata file. Human readable format is accepted: {+k,+M,+G}. For instance,
-\-\-max-size 5M
-.TP
-.BR "\-C, \-\-ctrl-url URL"
-Set control path URL. (Must use -D also)
-.TP
-.BR "\-D, \-\-data-url URL"
-Set data path URL. (Must use -C also)
-.RE
-.PP
-
-.PP
-\fBstart\fP [NAME] [OPTIONS]
-.RS
-Start tracing
-
-It will start tracing for all tracers for a specific tracing session.
-If NAME is omitted, the session name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBstop\fP [NAME] [OPTIONS]
-.RS
-Stop tracing
-
-It will stop tracing for all tracers for a specific tracing session. Before
-returning, the command checks for data availability meaning that it will wait
-until the trace is readable for the session. Use \-\-no-wait to avoid this
-behavior.
-
-If NAME is omitted, the session name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-\-no-wait"
-Don't wait for data availability.
-.RE
-.PP
-
-.PP
-\fBtrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
-.RS
-Adds one or more entries to a tracker
-
-The \fBtrack\fP command adds one or more entries to a tracker. A tracker is
-a whitelist of resources. Tracked resources are allowed to emit events, provided
-those events are enabled (see the \fBenable-event\fP command).
-
-Tracker entries can be removed from the whitelist with the
-\fBuntrack\fP command.
-
-As of this version, the only available tracker is the \fBPID tracker\fP. The
-process ID (PID) tracker follows one or more process IDs;
-only the processes with a tracked PID are allowed to emit events. By default,
-all possible PIDs on the system are tracked: any process may emit enabled
-events (equivalent of \fBlttng track \-\-pid \-\-all\fR for all domains).
-
-With the PID tracker, it is possible, for example, to record all system calls
-called by a given process:
-
-.nf
- $ lttng enable-event --kernel --all --syscall
- $ lttng track --kernel --pid 2345
- $ lttng start
-.fi
-
-If all the PIDs are tracked (i.e. \fBlttng track \-\-pid \-\-all\fR, which
-is the default state of all domains when creating a tracing session), then
-using the \fBtrack\fR command with one or more specific PIDs has the effect of
-first removing all the PIDs from the whitelist, then adding the specified PIDs.
-
-Assume the maximum PID is 7 for the following examples:
-
-.nf
- Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
-
- $ lttng track --userspace --pid 3,6,7
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-
- $ lttng untrack --userspace --pid 7
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-
- $ lttng track --userspace --pid 1,5
-
- Whitelist: [ ] [1] [ ] [3] [ ] [5] [6] [ ]
-.fi
-
-It should be noted that the PID tracker tracks the numeric process IDs.
-Should a process with a given ID exit and another process be given this
-ID, then the latter would also be allowed to emit events.
-
-See the \fBuntrack\fR command's documentation for more details about
-removing entries.
-
-.B OPTIONS:
-
-.TP
-.BR "\-s, \-\-session NAME"
-Apply to session name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer.
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user space tracer.
-.TP
-.BR "\-p, \-\-pid [PIDS]"
-Track process IDs PIDS (add to whitelist).
-
-PIDS is a comma-separated list of PIDs to add to the PID tracker.
-
-The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
-.TP
-.BR "\-a, \-\-all"
-Used in conjunction with an empty \fB\-\-pid\fP option: track all process IDs
-(add all entries to whitelist).
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBuntrack\fP (-k | -u) --pid [PID1[,PID2[,...]]] [OPTIONS]
-.RS
-Removes one or more entries from a tracker
-
-See the \fBtrack\fP command's documentation to learn more about LTTng
-trackers.
-
-The \fBuntrack\fP command removes specific resources from a tracker. The
-resources to remove must have been precedently added by the
-\fBtrack\fP command. It is also possible to remove all the resources
-from the whitelist using the \fB\-\-all\fR option.
-
-As of this version, the only available tracker is the \fBPID tracker\fP.
-
-One common operation is to create a tracing session, remove all the entries
-from the PID tracker whitelist, start tracing, and then manually track PIDs
-while tracing is active.
-
-Assume the maximum PID is 7 for the following examples:
-
-.nf
- $ lttng create
-
- Initial whitelist: [0] [1] [2] [3] [4] [5] [6] [7]
-
- $ lttng untrack --userspace --pid --all
-
- Whitelist: [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-
- $ lttng enable-event --userspace ...
- $ lttng start
- ...
- $ lttng track --userspace --pid 3,5
-
- Whitelist: [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-
- $ lttng track --userspace --pid 2
-
- Whitelist: [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-.fi
-
-See the \fBtrack\fR command's documentation for more details about
-adding entries.
-
-.B OPTIONS:
-
-.TP
-.BR "\-s, \-\-session NAME"
-Apply to session name.
-.TP
-.BR "\-k, \-\-kernel"
-Apply to the kernel tracer.
-.TP
-.BR "\-u, \-\-userspace"
-Apply to the user space tracer.
-.TP
-.BR "\-p, \-\-pid [PIDS]"
-Stop tracking process IDs PIDS (remove from whitelist).
-
-PIDS is a comma-separated list of PIDs to remove from the PID tracker.
-
-The PIDS argument must be omitted when also using the \fB\-\-all\fP option.
-.TP
-.BR "\-a, \-\-all"
-Used in conjunction with an empty \fB\-\-pid\fP option: stop tracking all
-process IDs (remove all entries from whitelist).
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBversion\fP
-.RS
-Show version information
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show summary of possible options and commands.
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.RE
-.PP
-
-.PP
-\fBview\fP [SESSION_NAME] [OPTIONS]
-.RS
-View traces of a tracing session. By default, the babeltrace viewer
-will be used for text viewing. If SESSION_NAME is omitted, the session
-name is taken from the .lttngrc file.
-
-.B OPTIONS:
-
-.TP
-.BR "\-h, \-\-help"
-Show this help
-.TP
-.BR "\-\-list-options"
-Simple listing of options
-.TP
-.BR "\-t, \-\-trace-path PATH"
-Trace directory path for the viewer
-.TP
-.BR "\-e, \-\-viewer CMD"
-Specify viewer and/or options to use This will completely override the
-default viewers so please make sure to specify the full command. The
-trace directory path of the session will be appended at the end to the
-arguments
-.RE
-.PP
-
-.SH "JUL/LOG4J DOMAIN"
-
-This section explains the JUL and LOG4J domain where JUL stands for Java Util
-Logging. You can use these by using the \fBliblttng-ust-<domain>-jni.so\fP from
-the lttng-ust(3) project.
-
-The LTTng Java Agent uses JNI to link the UST tracer to the Java application
-that uses the agent. Thus, it behaves similarly to the UST domain (\-u). When
-enabling events, you enable a Logger name that will then be mapped to a default
-UST tracepoint called \fBlttng_jul:<domain>_event\fP in the
-\fBlttng_<domain>_channel\fP. Using the lttng-ctl API, any JUL/LOG4J events
-must use the tracepoint event type (same as \-\-tracepoint).
-
-Because of the default immutable channel, the \fBenable-channel\fP command CAN
-NOT be used with the JUL and LOG4J domain thus not having any options.
-
-Also, loglevels are supported. Use \fBlttng enable-event \-h\fP to list them.
-Wildcards are NOT supported except the "*" meaning all events (same as \-a).
-
-Exactly like the UST domain, if the Java application has the same UID as you,
-you can trace it. Same goes for the tracing group accessing root applications.
-
-Finally, you can list every Logger name that are available from registered
-applications to the session daemon by using \fBlttng list \-j\fP or \fB\-l\fP.
-
-Here is an example on how to use the JUL domain.
-
-.nf
-$ lttng list -j
-[...]
-$ lttng create aSession
-$ lttng enable-event -s aSession -j MyCustomLoggerName
-$ lttng start
-.fi
-
-More information can be found in the lttng-ust documentation, see
-java-util-logging.txt
-.PP
-
-.SH "EXIT VALUES"
-.PP
-On success 0 is returned and a positive value on error. Value of 1 means a command
-error, 2 an undefined command, 3 a fatal error and 4 a command warning meaning that
-something went wrong during the command.
-
-Any other value above 10, please refer to
-.BR "<lttng/lttng-error.h>"
-for a detailed list or use lttng_strerror() to get a human readable string of
-the error code.
-.PP
-
-.SH "ENVIRONMENT VARIABLES"
-
-.PP
-Note that all command line options override environment variables.
-.PP
-
-.PP
-.IP "LTTNG_SESSIOND_PATH"
-Allows one to specify the full session daemon binary path to lttng command line
-tool. You can also use \-\-sessiond-path option having the same effect.
-.PP
-
-.PP
-.IP "LTTNG_SESSION_CONFIG_XSD_PATH"
-Set the path in which the \fBsession.xsd\fP session configuration schema may be
-found.
-.PP
-
-.SH "SEE ALSO"
-.BR babeltrace(1),
-.BR lttng-ust(3),
-.BR lttng-sessiond(8),
-.BR lttng-relayd(8),
-.BR lttng-crash(1),
-
-.SH "BUGS"
-
-.PP
-If you encounter any issues or usability problem, please report it on our
-mailing list <lttng-dev@lists.lttng.org> to help improve this project or
-at https://bugs.lttng.org which is a bug tracker.
-.PP
-
-.SH "CREDITS"
-
-.PP
-lttng is distributed under the GNU General Public License version 2. See the file
-COPYING for details.
-.PP
-A Web site is available at http://lttng.org for more information on the LTTng
-project.
-.PP
-You can also find our git tree at http://git.lttng.org.
-.PP
-Mailing lists for support and development: <lttng-dev@lists.lttng.org>.
-.PP
-You can find us on IRC server irc.oftc.net (OFTC) in #lttng.
-.PP
-.SH "THANKS"
-
-.PP
-Thanks to Yannick Brosseau without whom this project would never have been so
-lean and mean! Also thanks to the Ericsson teams working on tracing which
-helped us greatly with detailed bug reports and unusual test cases.
-
-Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
-maintainer) and Jon Bernard for our Debian packages.
-
-Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
-Montreal for the LTTng journey.
-.PP
-.SH "AUTHORS"
-
-.PP
-lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
-David Goulet. More people have since contributed to it. It is currently
-maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
-.PP
projects / lttng-tools.git / commitdiff
