X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=2.10%2Flttng-docs-2.10.txt;h=375fcf5cf4d716cae7c746e04ca242b8335203be;hb=3cd5f5046bca14706abaa8362af9741f9a86128f;hp=6d64ab86f41dc2ef8d16f4748b223fe7999c232b;hpb=57dea9c400ed153a8c4608a6d1a6d97536aeeef0;p=lttng-docs.git diff --git a/2.10/lttng-docs-2.10.txt b/2.10/lttng-docs-2.10.txt index 6d64ab8..375fcf5 100644 --- a/2.10/lttng-docs-2.10.txt +++ b/2.10/lttng-docs-2.10.txt @@ -1,12 +1,15 @@ The LTTng Documentation ======================= Philippe Proulx -v2.10, 19 November 2018 +v2.10, 25 February 2021 include::../common/copyright.txt[] +include::../common/warning-not-maintained.txt[] + + include::../common/welcome.txt[] @@ -297,6 +300,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 @@ -311,381 +316,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 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] -|xref:fedora[Fedora{nbsp}27, Fedora{nbsp}28, and Fedora{nbsp}29]. -|<>. - -|https://www.debian.org/[Debian] -|<>. -|<>. - -|https://www.archlinux.org/[Arch Linux] -|<>. -|<>. - -|https://alpinelinux.org/[Alpine Linux] -|<>. -|<>. - -|https://www.opensuse.org/[openSUSE] -|<>. -|<>. - -|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] -|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| - -|https://buildroot.org/[Buildroot] -|xref:buildroot[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]] -=== [[ubuntu-official-repositories]]Ubuntu - -LTTng{nbsp}{revision} is available on Ubuntu{nbsp}18.04 _Bionic Beaver_. -For previous supported releases of Ubuntu, -<>. - -To install LTTng{nbsp}{revision} on Ubuntu{nbsp}18.04 _Bionic Beaver_: - -. 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_ -* 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.10 -# 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}27, Fedora{nbsp}28, -or Fedora{nbsp}29: - -. 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.10.tar.bz2 && -tar -xf lttng-modules-latest-2.10.tar.bz2 && -cd lttng-modules-2.10.* && -make && -sudo make modules_install && -sudo depmod -a ----- --- - -[IMPORTANT] -.Java and Python application instrumentation and tracing -==== -If you need to instrument and trace <> on Fedora, 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 Fedora, you need to build and install -LTTng-UST{nbsp}{revision} from source and pass the -`--enable-python-agent` option to the `configure` script. -==== - - -[[debian]] -=== Debian - -To install LTTng{nbsp}{revision} on Debian "buster" (testing): - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -# apt-get install lttng-modules-dkms -# apt-get install liblttng-ust-dev -# apt-get install lttng-tools ----- --- - -. **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 ----- --- - - -[[arch-linux]] -=== Arch Linux - -LTTng-UST{nbsp}{revision} is available in Arch Linux's _Community_ -repository, while LTTng-tools{nbsp}{revision} and -LTTng-modules{nbsp}{revision} are available in the -https://aur.archlinux.org/[AUR]. - -To install LTTng{nbsp}{revision} on Arch Linux, using -https://github.com/rmarquis/pacaur[pacaur] for the AUR packages: - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -# pacman -Sy lttng-ust -$ pikaur -Sy lttng-tools -$ pikaur -Sy lttng-modules ----- --- - -. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: -+ --- -[role="term"] ----- -# pacman -Sy python-lttngust -# pacman -Sy python2-lttngust ----- --- - - -[[alpine-linux]] -=== Alpine Linux - -To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on -Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}3.8: - -. Add the LTTng packages: -+ --- -[role="term"] ----- -# apk add lttng-tools -# apk add lttng-ust-dev ----- --- - -. 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.10.tar.bz2 && -tar -xf lttng-modules-latest-2.10.tar.bz2 && -cd lttng-modules-2.10.* && -make && -sudo make modules_install && -sudo depmod -a ----- --- - - -[[opensuse]] -=== noch:{openSUSE} - -To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}15.0: - -* Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -sudo zypper install lttng-tools -sudo zypper install lttng-modules -sudo zypper install lttng-ust-devel ----- --- - -[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}2018.02, -Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08, or -Buildroot{nbsp}2018.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**. - [[building-from-source]] === Build from source @@ -868,22 +506,23 @@ tracepoints (this will generate a lot of data when tracing): . Do some operation on your system for a few seconds. For example, load a website, or list the files of a directory. -. <> and destroy the +. <> the current tracing session: + -- [role="term"] ---- -# lttng stop # lttng destroy ---- -- + -You need to stop tracing to make LTTng flush the remaining trace data -and make the trace readable. -+ The man:lttng-destroy(1) command does not destroy the trace data; it only destroys the state of the tracing session. ++ +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command +implicitly (see <>). You need to stop tracing to make LTTng flush the remaining +trace data and make the trace readable. . For the sake of this example, make the recorded trace accessible to the non-root users: @@ -1116,22 +755,23 @@ $ lttng start . Go back to the running `hello` application and press Enter. The program executes all `tracepoint()` instrumentation points and exits. -. <> and destroy the +. <> the current tracing session: + -- [role="term"] ---- -$ lttng stop $ lttng destroy ---- -- + -You need to stop tracing to make LTTng flush the remaining trace data -and make the trace readable. -+ The man:lttng-destroy(1) command does not destroy the trace data; it only destroys the state of the tracing session. ++ +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command +implicitly (see <>). You need to stop tracing to make LTTng flush the remaining +trace data and make the trace readable. By default, LTTng saves the traces in +$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+, @@ -1382,11 +1022,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. @@ -1397,7 +1037,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 @@ -1562,18 +1202,23 @@ 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, since LTTng 2.8, LTTng increments a count of lost sub-buffers when -a sub-buffer is lost and saves this count to the trace. In this mode, -the exact number of lost event records in those lost sub-buffers is not -saved to the trace. Trace analyses can use the trace's saved discarded -event record and sub-buffer counts to decide whether or not to perform -the analyses even if trace data is known to be missing. +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. <> shows -how you can fine-une the sub-buffer count and size of a channel to +how you can fine-tune the sub-buffer count and size of a channel to virtually stop losing event records, though at the cost of greater memory usage. @@ -4254,7 +3899,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. @@ -4416,7 +4061,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 @@ -5769,6 +5414,11 @@ $ lttng destroy ---- -- +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) +command implicitly (see <>). You need to stop tracing to make LTTng flush the +remaining trace data and make the trace readable. + [[list-instrumentation-points]] === List the available instrumentation points @@ -6118,7 +5768,10 @@ man:lttng-start(1), warnings are printed when you run the man:lttng-stop(1) command. IMPORTANT: You need to stop tracing to make LTTng flush the remaining -trace data and make the trace readable. +trace data and make the trace readable. Note that the +man:lttng-destroy(1) command (see +<>) also runs the man:lttng-stop(1) command implicitly. [[enabling-disabling-channels]]