From b80824bc133452c8f16fcf9978f8679c0b0a3ff1 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 18 Oct 2019 18:17:51 -0400 Subject: [PATCH] 2.11: finalize first publishable version of the LTTng 2.11 documentation Signed-off-by: Philippe Proulx --- 2.11/lttng-docs-2.11.txt | 430 ++++++++++++++++----------------------- 1 file changed, 171 insertions(+), 259 deletions(-) diff --git a/2.11/lttng-docs-2.11.txt b/2.11/lttng-docs-2.11.txt index 5752c97..6089b9f 100644 --- a/2.11/lttng-docs-2.11.txt +++ b/2.11/lttng-docs-2.11.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.11, 19 November 2018 +v2.11, 18 October 2019 include::../common/copyright.txt[] @@ -75,7 +75,7 @@ include::../common/acknowledgements.txt[] == What's new in LTTng{nbsp}{revision}? LTTng{nbsp}{revision} bears the name _Lafontaine_. This modern -https://en.wikipedia.org/wiki/Saison[saison] from the +https://en.wikipedia.org/wiki/saison[saison] from the https://oshlag.com/[Oshlag] microbrewery is a refreshing--zesty--rice beer with hints of fruit and spices. Some even say it makes for a great https://en.wikipedia.org/wiki/Somaek[Somaek] when mixed with @@ -132,8 +132,8 @@ $ lttng enable-event --kernel \ + The option also supports tracing existing https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SystemTap -Statically Defined Tracing] (SDT) probe (DTrace-style marker). For example, -given the following probe: +Statically Defined Tracing] (USDT) probe (DTrace-style marker). For +example, given the following probe: + [source,c] ---- @@ -180,21 +180,28 @@ user call stacks to the recorded event. NOTE: LTTng cannot always sample the user space call stack reliably. For instance, LTTng cannot sample the call stack of user applications and libraries compiled with the -https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html[`-fomit-frame pointer`] +https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html[`-fomit-frame-pointer`] option. In such a case, the tracing is not affected, but the sampled user space call stack may only contain the user call stack's topmost address. -* The <> is more efficient and presents fewer - connectivity issues, especially when a large number of targets send - trace data to a given relay daemon. - * User applications and libraries instrumented with <> can now safely unload (man:dlclose(3)) a dynamically loaded <>. +* The <> is more efficient and presents fewer + connectivity issues, especially when a large number of targets send + trace data to a given relay daemon. + +* LTTng-UST uses https://github.com/numactl/numactl[libnuma] + when available to allocate <>, making them + local to each + https://en.wikipedia.org/wiki/Non-uniform_memory_access[NUMA] node. ++ +This change makes the tracer more efficient on NUMA systems. + [[nuts-and-bolts]] == Nuts and bolts @@ -344,12 +351,15 @@ to <> (start and stop tracing, enable and disable event rules, and the rest). Those components are bundled into the following packages: -* **LTTng-tools**: Libraries and command-line interface to - control tracing. -* **LTTng-modules**: Linux kernel modules to instrument and - trace the kernel. -* **LTTng-UST**: Libraries and Java/Python packages to instrument and - trace user applications. +LTTng-tools:: + Libraries and command-line interface to control tracing. + +LTTng-modules:: + Linux kernel modules to instrument and trace the kernel. + +LTTng-UST:: + Libraries and Java/Python packages to instrument and trace user + applications. Most distributions mark the LTTng-modules and LTTng-UST packages as optional when installing LTTng-tools (which is always required). In the @@ -361,132 +371,14 @@ but note that: * You only need to install LTTng-UST if you intend to trace user applications. -[role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 12 November 2018. -|==== -|Distribution |Available in releases |Alternatives - -|https://www.ubuntu.com/[Ubuntu] -|Ubuntu{nbsp}14.04 _Trusty Tahr_, Ubuntu{nbsp}16.04 _Xenial Xerus_, -and Ubuntu{nbsp}18.04 _Bionic Beaver_: -<>. -|<>. - -|https://getfedora.org/[Fedora] -|_Not available_ -| -link:/docs/v2.10#doc-fedora[LTTng{nbsp}2.10 for Fedora{nbsp}27, -Fedora{nbsp}28, and Fedora{nbsp}29]. - -<>. - -|https://www.debian.org/[Debian] -|_Not available_ -|link:/docs/v2.10#doc-debian[LTTng{nbsp}2.10 for Debian "buster" (testing)]. - -<>. - -|https://www.archlinux.org/[Arch Linux] -|_Not available_ -|<>. - -|https://alpinelinux.org/[Alpine Linux] -|_Not available_ -| -link:/docs/v2.10#doc-alpine-linux[LTTng{nbsp}2.10 for -Alpine Linux{nbsp}3.7 and Alpine Linux{nbsp}3.8]. - -<>. - -|https://www.opensuse.org/[openSUSE] -|_Not available_ -|link:/docs/v2.10#doc-opensuse[LTTng{nbsp}2.10 for openSUSE Leap{nbsp}15.0]. - -<>. - -|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] -|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| - -|https://buildroot.org/[Buildroot] -|_Not available_ -| -link:/docs/v2.10#doc-buildroot[LTTng{nbsp}2.10 for Buildroot{nbsp}2018.02, -Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08, and Buildroot{nbsp}2018.11]. - -<>. - -|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and -https://www.yoctoproject.org/[Yocto] -|_Not available_ -|<>. -|==== - - -[[ubuntu-ppa]] -=== Ubuntu: noch:{LTTng} Stable {revision} PPA - -The https://launchpad.net/~lttng/+archive/ubuntu/stable-{revision}[LTTng -Stable{nbsp}{revision} PPA] offers the latest stable -LTTng{nbsp}{revision} packages for: - -* Ubuntu{nbsp}14.04 _Trusty Tahr_ -* Ubuntu{nbsp}16.04 _Xenial Xerus_ -* Ubuntu{nbsp}18.04 _Bionic Beaver_ - -To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: - -. Add the LTTng Stable{nbsp}{revision} PPA repository and update the - list of packages: -+ --- -[role="term"] ----- -# apt-add-repository ppa:lttng/stable-2.11 -# apt-get update ----- --- - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -# apt-get install lttng-tools -# apt-get install lttng-modules-dkms -# apt-get install liblttng-ust-dev ----- --- - -. **If you need to instrument and trace - <>**, install the LTTng-UST - Java agent: -+ --- -[role="term"] ----- -# apt-get install liblttng-ust-agent-java ----- --- - -. **If you need to instrument and trace - <>**, install the - LTTng-UST Python agent: -+ --- -[role="term"] ----- -# apt-get install python3-lttngust ----- --- - - -[[enterprise-distributions]] -=== RHEL, SUSE, and other enterprise distributions +[IMPORTANT] +==== +As of 18 October 2019, LTTng{nbsp}{revision} is not available +as distribution packages. -To install LTTng on enterprise Linux distributions, such as Red Hat -Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SUSE), please -see http://packages.efficios.com/[EfficiOS Enterprise Packages]. +You can <> +to install and use it. +==== [[building-from-source]] @@ -957,14 +849,14 @@ Once you have completed the <> and <> tutorials, you can inspect the recorded events. -Many tools are available to read LTTng traces: +There are many tools you can use to read LTTng traces: * **cmd:babeltrace** is a command-line utility which converts trace formats; it supports the format that LTTng produces, CTF, as well as a basic text output which can be ++grep++ed. The cmd:babeltrace command is part of the http://diamon.org/babeltrace[Babeltrace] project. * Babeltrace also includes - **https://www.python.org/[Python] bindings** so + **https://www.python.org/[Python{nbsp}3] bindings** so that you can easily open and read an LTTng trace with your own script, benefiting from the power of Python. * http://tracecompass.org/[**Trace Compass**] @@ -1013,7 +905,7 @@ $ babeltrace /tmp/my-kernel-trace | grep _open | wc --lines [[viewing-and-analyzing-your-traces-bt-python]] -==== Use the Babeltrace Python bindings +==== Use the Babeltrace{nbsp}1 Python bindings The <> is useful to isolate events by simple matching using man:grep(1) and @@ -1023,9 +915,9 @@ not trivial to write using a shell. Moreover, reductions and even the most basic computations involving multiple event records are virtually impossible to implement. -Fortunately, Babeltrace ships with Python{nbsp}3 bindings which makes it -easy to read the event records of an LTTng trace sequentially and -compute the desired information. +Fortunately, Babeltrace{nbsp}1 ships with Python{nbsp}3 bindings which +makes it easy to read the event records of an LTTng trace sequentially +and compute the desired information. The following script accepts an LTTng Linux kernel trace path as its first argument and prints the short names of the top five running @@ -1502,14 +1394,19 @@ files. When the number of trace files reaches the channel's fixed maximum count, the oldest trace file is overwritten. This mechanism is called _trace file rotation_. +[IMPORTANT] +==== Even if you don't limit the trace file count, you cannot assume that -LTTng doesn't manage any trace file. In other words, there is no safe -way to know if LTTng still holds a given trace file open with the trace -file rotation feature. The only way to obtain an unmanaged, -self-contained LTTng trace before you -<> the tracing session is -with the <> feature +LTTng doesn't manage any trace file. + +In other words, there is no safe way to know if LTTng still holds a +given trace file open with the trace file rotation feature. + +The only way to obtain an unmanaged, self-contained LTTng trace before +you <> the tracing session +is with the <> feature (available since LTTng{nbsp}2.11). +==== [[event]] @@ -5643,7 +5540,7 @@ Instead of using the default _tracepoint_ instrumentation type, use: . The entry point of a user application or library function (path to application/library and symbol). . A https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SystemTap - Statically Defined Tracing] (SDT) probe (path to application/library, + Statically Defined Tracing] (USDT) probe (path to application/library, provider and probe names). |Linux kernel. @@ -5801,7 +5698,7 @@ $ lttng enable-event --kernel --userspace-probe=/usr/lib/libc.so.6:malloc \ ---- ==== -.Create an event rule matching the `server`/`accept_request` https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SDT probe] in path:{/usr/bin/serv}: +.Create an event rule matching the `server`/`accept_request` https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[USDT probe] in path:{/usr/bin/serv}: ==== [role="term"] ---- @@ -6671,19 +6568,20 @@ overlaps. What LTTng is about to write when performing a tracing session rotation is called the _current trace chunk_. When this current trace chunk is -written to the file system or sent over the network, it is called a -_trace chunk archive_. Therefore, a tracing session rotation _archives_ -the current trace chunk. +written to the file system or sent over the network, it becomes a _trace +chunk archive_. Therefore, a tracing session rotation _archives_ the +current trace chunk. [role="img-100"] .A tracing session rotation operation _archives_ the current trace chunk. image::rotation.png[] -A trace chunk archive is a self-contained LTTng trace and is not managed -anymore by LTTng: you can read it, modify it, move it, or remove it. +A trace chunk archive is a self-contained LTTng trace which LTTng +doesn't manage anymore: you can read it, modify it, move it, or remove +it. -There are two methods to perform a tracing session rotation: -immediately or automatically. +There are two methods to perform a tracing session rotation: immediately +or with a rotation schedule. To perform an immediate tracing session rotation: @@ -6699,7 +6597,7 @@ $ lttng create my-session -- . <> -and <>: + and <>: + -- [role="term"] @@ -6725,8 +6623,8 @@ of trace chunk archive directory names. You can perform other immediate rotations while the tracing session is active. It is guaranteed that all the trace chunk archives do not contain overlapping trace data. You can also perform an immediate -rotation once the tracing session is -<>. +rotation once you have <> the +tracing session. . When you are done tracing, <> in _normal mode_ or _network streaming mode_ @@ -6779,12 +6675,12 @@ $ lttng enable-event --kernel sched_'*' -- [role="term"] ---- -$ lttng enable-rotation --timer=12s +$ lttng enable-rotation --timer=10s ---- -- + In this example, we set a rotation schedule so that LTTng performs a -tracing session rotation every 12{nbsp}seconds. +tracing session rotation every ten seconds. + See man:lttng-enable-rotation(1) to learn more about other ways to set a rotation schedule. @@ -6815,7 +6711,7 @@ $ lttng destroy The tracing session destruction operation creates one last trace chunk archive from the current trace chunk. -You can use man:lttng-disable-rotation(1) to unset an a tracing session +You can use man:lttng-disable-rotation(1) to unset a tracing session rotation schedule. NOTE: man:lttng-rotate(1) and man:lttng-enable-rotation(1) list @@ -7685,38 +7581,44 @@ commit the data to sub-buffers. Terms related to LTTng and to tracing in general: Babeltrace:: - The http://diamon.org/babeltrace[Babeltrace] project, which includes - the cmd:babeltrace command, libraries, and Python bindings. + The http://diamon.org/babeltrace[Babeltrace] project, which includes: ++ +* The cmd:babeltrace (Babeltrace{nbsp}1) or cmd:babeltrace2 + (Babeltrace{nbsp}2) command. +* Libraries with a C{nbsp}API. +* Python{nbsp}3 bindings. +* Plugins (Babeltrace{nbsp}2). [[def-buffering-scheme]]<>:: A layout of <> applied to a given channel. -<>:: +[[def-channel]]<>:: An entity which is responsible for a set of <>. + -<> are always attached to a specific channel. +<> are always attached to a specific +channel. clock:: A source of time for a <>. -<>:: +[[def-consumer-daemon]]<>:: A process which is responsible for consuming the full <> and write them to a file system or send them over the network. [[def-current-trace-chunk]]current trace chunk:: A <> which includes the current content - of all the <>'s + of all the <>'s <> and the stream files produced since the latest event amongst: + -* The creation of the tracing session. -* The last <>, if any. +* The creation of the <>. +* The last tracing session rotation, if any. -<>:: The event - record loss mode in which the <> _discards_ new - event records when there's no +<>:: + The <> in which + the <> _discards_ new event records when there's no <> space left to store them. [[def-event]]event:: @@ -7725,33 +7627,36 @@ clock:: <> that you manually place in some source code, or a Linux kernel kprobe. + -An event is said to _occur_ at a specific time. Different actions can -be taken upon the occurrence of an event, like record the event's payload -to a <>. +An event is said to _occur_ at a specific time. <> can +take various actions upon the occurrence of an event, like record the +event's payload to a <>. [[def-event-name]]event name:: - The name of an event, which is also the name of the event record. - This is also called the _instrumentation point name_. + The name of an <>, which is also the name of the + <>. ++ +This is also called the _instrumentation point name_. [[def-event-record]]event record:: - A record, in a <>, of the payload of an event - which occured. + A record, in a <>, of the payload of an + <> which occured. [[def-event-record-loss-mode]]<>:: - The mechanism by which event records of a given <> - are lost (not recorded) when there is no <> - space left to store them. + The mechanism by which event records of a given + <> are lost (not recorded) when there is no + <> space left to store them. -<>:: +[[def-event-rule]]<>:: Set of conditions which must be satisfied for one or more occuring - events to be recorded. + <> to be recorded. `java.util.logging`:: Java platform's https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[core logging facilities]. <>:: - The use of LTTng probes to make a piece of software traceable. + The use of <> probes to make a piece of software + traceable. [[def-instrumentation-point]]instrumentation point:: A point in the execution path of a piece of software that, when @@ -7766,29 +7671,31 @@ log4j:: log level:: Level of severity of a log statement or user space - instrumentation point. + <>. -LTTng:: +[[def-lttng]]LTTng:: The _Linux Trace Toolkit: next generation_ project. <>:: - A command-line tool provided by the LTTng-tools project which you - can use to send and receive control messages to and from a - session daemon. + A command-line tool provided by the <> + project which you can use to send and receive control messages to and + from a <>. LTTng analyses:: The https://github.com/lttng/lttng-analyses[LTTng analyses] project, - which is a set of analyzing programs that are used to obtain a - higher level view of an LTTng <>. + which is a set of analyzing programs that you can use to obtain a + higher level view of an <> <>. cmd:lttng-consumerd:: - The name of the consumer daemon program. + The name of the <> program. cmd:lttng-crash:: - A utility provided by the LTTng-tools project which can convert - <> files (usually - <>) - to <> files. + A utility provided by the <> project + which can convert <> files (usually + <>) to <> files. ++ +See man:lttng-crash(1). LTTng Documentation:: This document. @@ -7796,38 +7703,40 @@ LTTng Documentation:: <>:: A communication protocol between the <> and live viewers which makes it possible to see <> "live", as they are received by the relay daemon. + records>> "live", as they are received by the + <>. <>:: The https://github.com/lttng/lttng-modules[LTTng-modules] project, which contains the Linux kernel modules to make the Linux kernel <> available for - LTTng tracing. + <> tracing. cmd:lttng-relayd:: - The name of the <> program. + The name of the <> program. cmd:lttng-sessiond:: - The name of the <> program. + The name of the <> program. -LTTng-tools:: +[[def-lttng-tools]]LTTng-tools:: The https://github.com/lttng/lttng-tools[LTTng-tools] project, which contains the various programs and libraries used to <>. -<>:: +[[def-lttng-ust]]<>:: The https://github.com/lttng/lttng-ust[LTTng-UST] project, which contains libraries to instrument <>. <>:: - A Java package provided by the LTTng-UST project to allow the - LTTng instrumentation of `java.util.logging` and Apache log4j{nbsp}1.2 - logging statements. + A Java package provided by the <> project to + allow the LTTng instrumentation of `java.util.logging` and Apache + log4j{nbsp}1.2 logging statements. <>:: - A Python package provided by the LTTng-UST project to allow the - LTTng instrumentation of Python logging statements. + A Python package provided by the <> project + to allow the <> instrumentation of Python logging + statements. <>:: The <> in which new @@ -7838,16 +7747,16 @@ LTTng-tools:: <>:: A <> in which each instrumented process has its own <> for a given user - space <>. + space <>. <>:: A <> in which all the processes of a Unix user share the same <> for a - given user space <>. + given user space <>. -<>:: +[[def-relay-daemon]]<>:: A process which is responsible for receiving the <> - data sent by a distant <>. + data which a distant <> sends. [[def-ring-buffer]]ring buffer:: A set of <>. @@ -7855,22 +7764,22 @@ LTTng-tools:: rotation:: See _<>_. -<>:: +[[def-session-daemon]]<>:: A process which receives control commands from you and orchestrates - the <> and various LTTng daemons. + the <> and various <> daemons. <>:: A copy of the current data of all the <> - of a given <>, saved as + of a given <>, saved as <> files. [[def-sub-buffer]]sub-buffer:: - One part of an LTTng <> which contains - <>. + One part of an <> <> + which contains <>. timestamp:: - The time information attached to an - <> when it is emitted. + The time information attached to an <> when it is + emitted. [[def-trace]]trace (_noun_):: A set of: @@ -7879,46 +7788,50 @@ timestamp:: * One or more CTF data stream files which are the concatenations of one or more flushed <>. -trace (_verb_):: +[[def-trace-verb]]trace (_verb_):: The action of recording the <> emitted by an application or by a system, or to initiate such recording by - controlling a tracer. + controlling a <>. [[def-trace-chunk]]trace chunk:: - A self-contained trace which is part of a <>. Each <> - produces a trace chunk archive. + A self-contained <> which is part of a + <>. Each + <> produces a + <>. -trace chunk archive:: - The result of a <>. A - trace chunk archive is not managed by LTTng, even if its containing - <> is still active: you are free to - read it, modify it, move it, or remove it. +[[def-trace-chunk-archive]]trace chunk archive:: + The result of a <>. ++ +<> does not manage any trace chunk archive, even if its +containing <> is still active: you +are free to read it, modify it, move it, or remove it. Trace Compass:: The http://tracecompass.org[Trace Compass] project and application. [[def-tracepoint]]tracepoint:: An instrumentation point using the tracepoint mechanism of the Linux - kernel or of LTTng-UST. + kernel or of <>. tracepoint definition:: - The definition of a single tracepoint. + The definition of a single <>. tracepoint name:: - The name of a tracepoint. + The name of a <>. -tracepoint provider:: - A set of functions providing tracepoints to an instrumented user - application. +[[def-tracepoint-provider]]tracepoint provider:: + A set of functions providing <> to an + instrumented <>. + -Not to be confused with a _tracepoint provider package_: many tracepoint -providers can exist within a tracepoint provider package. +Not to be confused with a <>: many tracepoint providers can exist within a +tracepoint provider package. -tracepoint provider package:: - One or more tracepoint providers compiled as an - https://en.wikipedia.org/wiki/Object_file[object file] or as - a link:https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries[shared library]. +[[def-tracepoint-provider-package]]tracepoint provider package:: + One or more <> compiled + as an https://en.wikipedia.org/wiki/Object_file[object file] or as a + link:https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries[shared + library]. [[def-tracer]]tracer:: A software which records emitted <>. @@ -7927,17 +7840,16 @@ tracepoint provider package:: A namespace for <> sources. <>:: - The Unix group in which a Unix user can be to be allowed to trace the - Linux kernel. + The Unix group in which a Unix user can be to be allowed to + <> the Linux kernel. -[[def-tracing-session-rotation]]<>:: - A stateful dialogue between you and a <>. +[[def-tracing-session]]<>:: + A stateful dialogue between you and a <>. -<>:: +[[def-tracing-session-rotation]]<>:: The action of archiving the <> of a - <>. + <>. [[def-user-application]]user application:: An application running in user space, as opposed to a Linux kernel -- 2.34.1