X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=9ccf4caa8017f6bc9e250bd3f6398c4f08fb0897;hb=HEAD;hp=f69a074603b7dd6d1893068928bdbf66a186f50a;hpb=01b2f702118f65edddee788f1b407580b0074599;p=lttng-docs.git diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt index f69a074..9ccf4ca 100644 --- a/2.8/lttng-docs-2.8.txt +++ b/2.8/lttng-docs-2.8.txt @@ -1,12 +1,15 @@ The LTTng Documentation ======================= Philippe Proulx -v2.8, 14 March 2017 +v2.8, 25 February 2021 include::../common/copyright.txt[] +include::../common/warning-not-maintained.txt[] + + include::../common/welcome.txt[] @@ -357,6 +360,8 @@ becomes inactive or in real-time. [[installing-lttng]] == Installation +include::../common/warning-no-installation.txt[] + **LTTng** is a set of software <> which interact to <> the Linux kernel and user applications, and to <> (start and stop @@ -371,305 +376,14 @@ components are bundled into the following packages: 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 -following sections, we always provide the steps to install all three, -but note that: +optional when installing LTTng-tools (which is always required). Note +that: * You only need to install LTTng-modules if you intend to trace the Linux kernel. * 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 14 March 2017. -|==== -|Distribution |Available in releases |Alternatives - -|https://www.ubuntu.com/[Ubuntu] -|<>. -|LTTng{nbsp}{revision} for Ubuntu{nbsp}14.04 _Trusty Tahr_ -and Ubuntu{nbsp}16.04 _Xenial Xerus_: -<>. - -LTTng{nbsp}2.9 for Ubuntu{nbsp}14.04 _Trusty Tahr_ -and Ubuntu{nbsp}16.04 _Xenial Xerus_: -link:/docs/v2.9#doc-ubuntu-ppa[use the LTTng Stable{nbsp}2.9 PPA]. - -LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ (not released -yet). - -<> for -other Ubuntu releases. - -|https://getfedora.org/[Fedora] -|<>. -|<> for -other Fedora releases. - -|https://www.debian.org/[Debian] -|_Not available_ -|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" (testing) -and Debian "sid" (unstable)]. - -<>. - -|https://www.opensuse.org/[openSUSE] -|_Not available_ -|<>. - -|https://www.archlinux.org/[Arch Linux] -|_Not available_ -|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR]. - -<>. - -|https://alpinelinux.org/[Alpine Linux] -|_Not available_ -|link:/docs/v2.9#doc-alpine-linux[LTTng{nbsp}2.9 for Alpine Linux "edge"]. - -<>. - -|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] -|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| - -|https://buildroot.org/[Buildroot] -|<>. -|link:/docs/v2.9#doc-buildroot[LTTng{nbsp}2.9 for Buildroot 2017.02]. - -<> for -other Buildroot releases. - -|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and -https://www.yoctoproject.org/[Yocto] -|<> (`openembedded-core` layer). -|LTTng{nbsp}2.9 for Yocto Project{nbsp}2.3 _Pyro_ -(`openembedded-core` layer) (not released yet). - -<> for -other OpenEmbedded releases. -|==== - - -[[ubuntu]] -=== [[ubuntu-official-repositories]]Ubuntu - -LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.10 _Yakkety Yak_. -For previous releases of Ubuntu, <>. - -To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.10 _Yakkety Yak_: - -. 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 ----- --- - - -[[ubuntu-ppa]] -==== 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_ - -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.8 -# 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 ----- --- - - -[[fedora]] -=== Fedora - -To install LTTng{nbsp}{revision} on Fedora{nbsp}25: - -. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} - packages: -+ --- -[role="term"] ----- -# yum install lttng-tools -# yum install lttng-ust ----- --- - -. Download, build, and install the latest LTTng-modules{nbsp}{revision}: -+ --- -[role="term"] ----- -$ cd $(mktemp -d) && -wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.8.tar.bz2 && -tar -xf lttng-modules-latest-2.8.tar.bz2 && -cd lttng-modules-2.8.* && -make && -sudo make modules_install && -sudo depmod -a ----- --- - -[IMPORTANT] -.Java and Python application instrumentation and tracing -==== -If you need to instrument and trace <> on openSUSE, you need to build and install -LTTng-UST{nbsp}{revision} <> and pass -the `--enable-java-agent-jul`, `--enable-java-agent-log4j`, or -`--enable-java-agent-all` options to the `configure` script, depending -on which Java logging framework you use. - -If you need to instrument and trace <> on openSUSE, you need to build and install -LTTng-UST{nbsp}{revision} from source and pass the -`--enable-python-agent` option to the `configure` script. -==== - - -[[enterprise-distributions]] -=== RHEL, SUSE, and other enterprise distributions - -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]. - - -[[buildroot]] -=== Buildroot - -To install LTTng{nbsp}{revision} on Buildroot{nbsp}2016.11: - -. Launch the Buildroot configuration tool: -+ --- -[role="term"] ----- -$ make menuconfig ----- --- - -. In **Kernel**, check **Linux kernel**. -. In **Toolchain**, check **Enable WCHAR support**. -. In **Target packages**{nbsp}→ **Debugging, profiling and benchmark**, - check **lttng-modules** and **lttng-tools**. -. In **Target packages**{nbsp}→ **Libraries**{nbsp}→ - **Other**, check **lttng-libust**. - - -[[oe-yocto]] -=== OpenEmbedded and Yocto - -LTTng{nbsp}{revision} recipes are available in the -http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/[`openembedded-core`] -layer for Yocto Project{nbsp}2.2 _Morty_ under the following names: - -* `lttng-tools` -* `lttng-modules` -* `lttng-ust` - -With BitBake, the simplest way to include LTTng recipes in your target -image is to add them to `IMAGE_INSTALL_append` in path:{conf/local.conf}: - ----- -IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust" ----- - -If you use Hob: - -. Select a machine and an image recipe. -. Click **Edit image recipe**. -. Under the **All recipes** tab, search for **lttng**. -. Check the desired LTTng recipes. - -[IMPORTANT] -.Java and Python application instrumentation and tracing -==== -If you need to instrument and trace <> on openSUSE, you need to build and install -LTTng-UST{nbsp}{revision} <> and pass -the `--enable-java-agent-jul`, `--enable-java-agent-log4j`, or -`--enable-java-agent-all` options to the `configure` script, depending -on which Java logging framework you use. - -If you need to instrument and trace <> on openSUSE, you need to build and install -LTTng-UST{nbsp}{revision} from source and pass the -`--enable-python-agent` option to the `configure` script. -==== - [[building-from-source]] === Build from source @@ -1360,11 +1074,11 @@ LTTng can send the generated trace data to different locations. The _tracing session mode_ dictates where to send it. The following modes are available in LTTng{nbsp}{revision}: -Local mode:: +[[local-mode]]Local mode:: LTTng writes the traces to the file system of the machine being traced (target system). -Network streaming mode:: +[[net-streaming-mode]]Network streaming mode:: LTTng sends the traces over the network to a <> running on a remote system. @@ -1375,7 +1089,7 @@ Snapshot mode:: or to send it over the network to a <> running on a remote system. -Live mode:: +[[live-mode]]Live mode:: This mode is similar to the network streaming mode, but a live trace viewer can connect to the distant relay daemon to <> by @@ -1530,10 +1244,19 @@ as soon as a there's no space left for a new event record, whereas in discard mode, the tracer only discards the event record that doesn't fit. -In discard mode, LTTng increments a count of lost event records when -an event record is lost and saves this count to the trace. In -overwrite mode, LTTng keeps no information when it overwrites a -sub-buffer before consuming it. +In discard mode, LTTng increments a count of lost event records when an +event record is lost and saves this count to the trace. Since +LTTng{nbsp}2.8, in overwrite mode, LTTng writes to a given sub-buffer +its sequence number within its data stream. With a <>, +<>, or <> +<>, a trace reader can use such +sequence numbers to report lost packets. In overwrite mode, LTTng +doesn't write to the trace the exact number of lost event records in +those lost sub-buffers. + +Trace analyses can use saved discarded event record and sub-buffer +(packet) counts of the trace to decide whether or not to perform the +analyses even if trace data is known to be missing. There are a few ways to decrease your probability of losing event records. @@ -1558,8 +1281,8 @@ to configure the sub-buffer count and size for them: * **High event throughput**: In general, prefer bigger sub-buffers to lower the risk of losing event records. + -Having bigger sub-buffers also ensures a lower sub-buffer switching -frequency. +Having bigger sub-buffers also ensures a lower +<>. + The number of sub-buffers is only meaningful if you create the channel in overwrite mode: in this case, if a sub-buffer overwrite happens, the @@ -1713,7 +1436,7 @@ With so many similar terms, it's easy to get confused. An **event** is the consequence of the execution of an _instrumentation point_, like a tracepoint 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 occurance of an event, +time. Different actions can be taken upon the occurrence of an event, like record the event's payload to a buffer. An **event record** is the representation of an event in a sub-buffer. A @@ -1748,7 +1471,7 @@ The LTTng project incorporates: * **LTTng-tools**: Libraries and command-line interface to control tracing sessions. ** <> (man:lttng-sessiond(8)). -** <> (man:lttng-consumerd(8)). +** <> (cmd:lttng-consumerd). ** <> (man:lttng-relayd(8)). ** <> (`liblttng-ctl`). ** <> (man:lttng(1)). @@ -2044,7 +1767,7 @@ running. You can also start the session daemon manually. .The consumer daemon. image::plumbing-consumerd.png[] -The _consumer daemon_, man:lttng-consumerd(8), is a daemon which shares +The _consumer daemon_, cmd:lttng-consumerd, is a daemon which shares ring buffers with user applications or with the LTTng kernel modules to collect trace data and send it to some location (on disk or to a <> over the network). The consumer daemon @@ -4201,7 +3924,7 @@ $ lttng enable-event --userspace 'lttng_ust_tracelog:*' [[prebuilt-ust-helpers]] === Prebuilt user space tracing helpers -The LTTng-UST package provides a few helpers in the form or preloadable +The LTTng-UST package provides a few helpers in the form of preloadable shared objects which automatically instrument system functions and calls. @@ -4363,7 +4086,7 @@ logging frameworks: .LTTng-UST Java agent imported by a Java application. image::java-app.png[] -Note that the methods described below are new in LTTng{nbsp}{revision}. +Note that the methods described below are new in LTTng{nbsp}2.8. Previous LTTng versions use another technique. NOTE: We use http://openjdk.java.net/[OpenJDK]{nbsp}8 for development @@ -5331,12 +5054,12 @@ MODULE_VERSION(__stringify(LTTNG_MODULES_MAJOR_VERSION) "." ---- -- -. Edit path:{probes/Makefile} and add your new kernel module object +. Edit path:{probes/KBuild} and add your new kernel module object next to the existing ones: + -- [source,make] -.path:{probes/Makefile} +.path:{probes/KBuild} ---- # ... @@ -6389,8 +6112,8 @@ leads to this whitelist: .PIDs 3, 7, 10, and 13 are removed from the whitelist. image::track-1-4-15-16.png[] -LTTng can track all possible PIDs again using the opt:track(1):--all -option: +LTTng can track all possible PIDs again using the +opt:lttng-track(1):--all option: [role="term"] ---- @@ -7200,7 +6923,7 @@ event:: or a Linux kernel KProbe. + An event is said to _occur_ at a specific time. Different actions can -be taken upon the occurance of an event, like record the event's payload +be taken upon the occurrence of an event, like record the event's payload to a sub-buffer. <>::