X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=2.10%2Flttng-docs-2.10.txt;h=47fc1af415a5199cab97c1237728c30574795fac;hb=763bc98560eb270927ba0f8786baf4beed7e7c42;hp=bbcb2479b5ec3be729fc0c07cde0d90af5b394b1;hpb=51a225a5ce0bff31b367c0e5ef54feba5ba1d9c2;p=lttng-docs.git diff --git a/2.10/lttng-docs-2.10.txt b/2.10/lttng-docs-2.10.txt index bbcb247..47fc1af 100644 --- a/2.10/lttng-docs-2.10.txt +++ b/2.10/lttng-docs-2.10.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.10, 22 January 2018 +v2.10, 18 October 2019 include::../common/copyright.txt[] @@ -321,73 +321,104 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 22 January 2018. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 18 October 2019. |==== -|Distribution |Available in releases |Alternatives +|Distribution |Available in releases |https://www.ubuntu.com/[Ubuntu] -|Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_: -<>. -|link:/docs/v2.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ and Ubuntu{nbsp}17.10 _Artful Aardvark_]. +|xref:ubuntu[Ubuntu{nbsp}18.04 _Bionic Beaver_, +Ubuntu{nbsp}19.04 _Disco Dingo_, and +Ubuntu{nbsp}19.10 _Eoan Ermine_]. -<> for -other Ubuntu releases. +Ubuntu{nbsp}16.04 _Xenial Xerus_: +<>. |https://getfedora.org/[Fedora] -|<>. -|link:/docs/v2.9#doc-fedora[LTTng{nbsp}2.9 for Fedora{nbsp}26]. - -<> for -other Fedora releases. +|xref:fedora[Fedora{nbsp}29, Fedora{nbsp}30, Fedora{nbsp}31, +and Fedora{nbsp}32]. |https://www.debian.org/[Debian] -|<>. -|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" (stable)]. - -<>. - -|https://www.archlinux.org/[Arch Linux] -|<>. -|<>. +|<>. |https://alpinelinux.org/[Alpine Linux] -|<>. -|<>. +|xref:alpine-linux[Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8, +Alpine Linux{nbsp}3.9, and Alpine Linux{nbsp}3.10]. + +|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] -|_Not available_ -|link:/docs/v2.9#doc-buildroot[LTTng{nbsp}2.9 for Buildroot{nbsp}2017.02, -Buildroot{nbsp}2017.05, Buildroot{nbsp}2017.08, and Buildroot{nbsp}2017.11]. - -<>. +|xref:buildroot[Buildroot{nbsp}2018.02, Buildroot{nbsp}2018.05, +Buildroot{nbsp}2018.08, Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.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_ -|link:/docs/v2.9#doc-oe-yocto[LTTng{nbsp}2.9 for Yocto Project{nbsp}2.3 _Pyro_ -and Yocto Project{nbsp}2.4 _Rocko_] -(`openembedded-core` layer). - -<>. +|<>. |==== [[ubuntu]] === [[ubuntu-official-repositories]]Ubuntu +LTTng{nbsp}{revision} is available on: + +* Ubuntu{nbsp}18.04 _Bionic Beaver_ +* Ubuntu{nbsp}19.04 _Disco Dingo_ +* Ubuntu{nbsp}19.10 _Eoan Ermine_ + +For other releases of Ubuntu, <>. + +To install LTTng{nbsp}{revision} on Ubuntu{nbsp}18.04 _Bionic Beaver_, +Ubuntu{nbsp}19.04 _Disco Dingo_, or +Ubuntu{nbsp}19.10 _Eoan Ermine_: + +. 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_ +LTTng{nbsp}{revision} packages for Ubuntu{nbsp}18.04 _Bionic Beaver_. To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: @@ -439,7 +470,8 @@ To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: [[fedora]] === Fedora -To install LTTng{nbsp}{revision} on Fedora{nbsp}27: +To install LTTng{nbsp}{revision} on Fedora{nbsp}29, Fedora{nbsp}30, +Fedora{nbsp}31, or Fedora{nbsp}32: . Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} packages: @@ -487,8 +519,8 @@ LTTng-UST{nbsp}{revision} from source and pass the [[debian]] === Debian -To install LTTng{nbsp}{revision} on Debian "buster" (testing) -or Debian "sid" (unstable): +To install LTTng{nbsp}{revision} on Debian "buster" (stable) or +Debian "bullseye" (testing): . Install the main LTTng{nbsp}{revision} packages: + @@ -522,97 +554,147 @@ or Debian "sid" (unstable): -- -[[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]. +[[alpine-linux]] +=== Alpine Linux -To install LTTng{nbsp}{revision} on Arch Linux, using -https://github.com/rmarquis/pacaur[pacaur] for the AUR packages: +To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on +Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8, Alpine Linux{nbsp}3.9, or +Alpine Linux{nbsp}3.10: -. Install the main LTTng{nbsp}{revision} packages: +. Add the LTTng packages: + -- [role="term"] ---- -# pacman -Sy lttng-ust -$ pacaur -Sy lttng-tools -$ pacaur -Sy lttng-modules +# apk add lttng-tools +# apk add lttng-ust-dev ---- -- -. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: +. Download, build, and install the latest LTTng-modules{nbsp}{revision}: + -- [role="term"] ---- -# pacman -Sy python-lttngust -# pacman -Sy python2-lttngust +$ 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 ---- -- -[[alpine-linux]] -=== Alpine Linux +[[opensuse]] +=== noch:{openSUSE} -To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on -Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}"edge": - -. **If you're installing for Alpine Linux{nbsp}"edge"**, make sure your - system is https://wiki.alpinelinux.org/wiki/Edge[configured for - "edge"]. -. **If you're installing for Alpine Linux{nbsp}"edge"**, enable the _testing_ - repository by uncommenting the corresponding line in - path:{/etc/apk/repositories}. -. Add the LTTng packages: +To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}15.1: + +* Install the main LTTng{nbsp}{revision} packages: + -- [role="term"] ---- -# apk add lttng-tools -# apk add lttng-ust-dev +sudo zypper install lttng-tools +sudo zypper install lttng-modules +sudo zypper install lttng-ust-devel ---- -- -To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support) -on Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}"edge": +[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. +==== + -. Add the vanilla Linux kernel: +[[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, +Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.02, +Buildroot{nbsp}2019.05, Buildroot{nbsp}2019.08, or +Buildroot{nbsp}2019.11: + +. Launch the Buildroot configuration tool: + -- [role="term"] ---- -# apk add linux-vanilla linux-vanilla-dev +$ make menuconfig ---- -- -. Reboot with the vanilla Linux kernel. -. Download, build, and install the latest LTTng-modules{nbsp}{revision}: -+ --- -[role="term"] +. 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.7 _Warrior_ and +Yocto Project{nbsp}3.0 _Zeus_ 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}: + ---- -$ 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 +IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust" ---- --- +If you use Hob: -[[enterprise-distributions]] -=== RHEL, SUSE, and other enterprise distributions +. Select a machine and an image recipe. +. Click **Edit image recipe**. +. Under the **All recipes** tab, search for **lttng**. +. Check the desired LTTng recipes. -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]. +[IMPORTANT] +.Java and Python application instrumentation and tracing +==== +If you need to instrument and trace <> on Yocto/OpenEmbedded, 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 Yocto/OpenEmbedded, 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]] @@ -796,19 +878,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 ---- -- + 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: @@ -1041,19 +1127,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 ---- -- + 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__+, @@ -1495,7 +1585,7 @@ 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. @@ -5691,6 +5781,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 @@ -6039,6 +6134,12 @@ records>> or lost sub-buffers since the last time you ran 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. Note that the +man:lttng-destroy(1) command (see +<>) also runs the man:lttng-stop(1) command implicitly. + [[enabling-disabling-channels]] === Create a channel