X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;ds=inline;f=2.9%2Flttng-docs-2.9.txt;h=7fe1dbe9c24520b9adb689dff39696b3df33bcf6;hb=35df69388ff1fdf8a57e81832f64fb1fc132054c;hp=203b81dad858cc374d3a1c3d4e000bd559852126;hpb=c04688407cf6ad1e0d92022f9002317b9be2d22b;p=lttng-docs.git diff --git a/2.9/lttng-docs-2.9.txt b/2.9/lttng-docs-2.9.txt index 203b81d..7fe1dbe 100644 --- a/2.9/lttng-docs-2.9.txt +++ b/2.9/lttng-docs-2.9.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.9, 24 July 2017 +v2.9, 22 January 2018 include::../common/copyright.txt[] @@ -340,97 +340,73 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 14 March 2017. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 22 January 2018. |==== |Distribution |Available in releases |Alternatives |https://www.ubuntu.com/[Ubuntu] -|Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_: -<>. -|link:/docs/v2.8#doc-ubuntu[LTTng{nbsp}2.8 for Ubuntu{nbsp}16.10 _Yakkety Yak_]. - -LTTng{nbsp}{revision} for Ubuntu{nbsp}17.04 _Zesty Zapus_ (not released -yet). +|<>. -<> for +Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_: +<>. +|<> for other Ubuntu releases. |https://getfedora.org/[Fedora] -|_Not available_ -|link:/docs/v2.8#doc-fedora[LTTng{nbsp}2.8 for Fedora 25]. +|<>. +|link:/docs/v2.10#doc-fedora[LTTng{nbsp}2.10 for Fedora{nbsp}27]. -<>. +<> for +other Fedora releases. |https://www.debian.org/[Debian] -|<>. -|<> for +|<>. +|link:/docs/v2.10#doc-debian[LTTng{nbsp}2.10 for Debian "buster" (testing) +and Debian "sid" (unstable)]. + + +<> for other Debian releases. -|https://www.opensuse.org/[openSUSE] +|https://www.archlinux.org/[Arch Linux] |_Not available_ -|<>. +|link:/docs/v2.10#doc-arch-linux[LTTng{nbsp}2.10 for the current Arch Linux build]. -|https://www.archlinux.org/[Arch Linux] -|<>. -| +<>. |https://alpinelinux.org/[Alpine Linux] -|<>. -|<> for -other Alpine Linux releases. +|_Not available_ +|link:/docs/v2.10#doc-alpine-linux[LTTng{nbsp}2.10 for Alpine Linux{nbsp}3.7 +and Alpine Linux{nbsp}"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.8#doc-buildroot[LTTng{nbsp}2.8 for Buildroot 2016.11]. - -<> for +|<<"buildroot", "Buildroot{nbsp}2017.02, Buildroot{nbsp}2017.05, Buildroot{nbsp}2017.08, and Buildroot{nbsp}2017.11">>. +|<> for other Buildroot releases. |http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and https://www.yoctoproject.org/[Yocto] -|_Not available_ -|link:/docs/v2.8#doc-oe-yocto[LTTng{nbsp}2.8 for Yocto Project{nbsp}2.2 _Morty_] +|<> (`openembedded-core` layer). - -LTTng{nbsp}{revision} for Yocto Project{nbsp}2.3 _Pyro_ -(`openembedded-core` layer) (not released yet). - -<> for -other OpenEmbedded releases. +|<> for +other Yocto/OpenEmbedded releases. |==== [[ubuntu]] === [[ubuntu-official-repositories]]Ubuntu -[[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: +LTTng{nbsp}{revision} is available on Ubuntu{nbsp}17.04 _Zesty Zapus_ +and Ubuntu{nbsp}17.10 _Artful Aardvark_. For previous releases of +Ubuntu, <>. -* 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.9 -# apt-get update ----- --- +To install LTTng{nbsp}{revision} on Ubuntu{nbsp}17.04 _Zesty Zapus_: . Install the main LTTng{nbsp}{revision} packages: + @@ -466,25 +442,43 @@ To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: -- -[[debian]] -=== Debian +[[ubuntu-ppa]] +==== noch:{LTTng} Stable {revision} PPA -To install LTTng{nbsp}{revision} on Debian "stretch" (testing) or -Debian "sid" (unstable): +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.9 +# 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 -# apt-get install lttng-tools ---- -- -. **If you need to instrument and trace <>**, install the LTTng-UST Java agent: +. **If you need to instrument and trace + <>**, install the LTTng-UST + Java agent: + -- [role="term"] @@ -493,8 +487,9 @@ Debian "sid" (unstable): ---- -- -. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: +. **If you need to instrument and trace + <>**, install the + LTTng-UST Python agent: + -- [role="term"] @@ -504,80 +499,87 @@ Debian "sid" (unstable): -- -[[arch-linux]] -=== Arch Linux +[[fedora]] +=== Fedora -To install LTTng{nbsp}{revision} on Arch Linux using -https://archlinux.fr/yaourt-en[Yaourt]: +To install LTTng{nbsp}{revision} on Fedora{nbsp}26: -. Install the main LTTng{nbsp}{revision} packages: +. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} + packages: + -- [role="term"] ---- -$ yaourt -S lttng-tools -$ yaourt -S lttng-ust -$ yaourt -S lttng-modules +# yum install lttng-tools +# yum install lttng-ust ---- -- -. **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"] ---- -$ yaourt -S python-lttngust -$ yaourt -S python2-lttngust +$ cd $(mktemp -d) && +wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.9.tar.bz2 && +tar -xf lttng-modules-latest-2.9.tar.bz2 && +cd lttng-modules-2.9.* && +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. +==== + -[[alpine-linux]] -=== Alpine Linux +[[debian]] +=== Debian -To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on -Alpine Linux "edge": +To install LTTng{nbsp}{revision} on Debian "stretch" (stable): -. Make sure your system is - https://wiki.alpinelinux.org/wiki/Edge[configured for "edge"]. -. Enable the _testing_ repository by uncommenting the corresponding - line in path:{/etc/apk/repositories}. -. Add the LTTng packages: +. Install the main LTTng{nbsp}{revision} packages: + -- [role="term"] ---- -# apk add lttng-tools -# apk add lttng-ust-dev +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev +# apt-get install lttng-tools ---- -- -To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support) -on Alpine Linux "edge": - -. Add the vanilla Linux kernel: +. **If you need to instrument and trace <>**, install the LTTng-UST Java agent: + -- [role="term"] ---- -# apk add linux-vanilla linux-vanilla-dev +# apt-get install liblttng-ust-agent-java ---- -- -. Reboot with the vanilla Linux kernel. -. Download, build, and install the latest LTTng-modules{nbsp}{revision}: +. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: + -- [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 +# apt-get install python3-lttngust ---- -- @@ -593,7 +595,9 @@ see http://packages.efficios.com/[EfficiOS Enterprise Packages]. [[buildroot]] === Buildroot -To install LTTng{nbsp}{revision} on Buildroot{nbsp}2017.02: +To install LTTng{nbsp}{revision} on Buildroot{nbsp}2017.02, +Buildroot{nbsp}2017.05, Buildroot{nbsp}2017.08, or +Buildroot{nbsp}2017.11: . Launch the Buildroot configuration tool: + @@ -612,6 +616,49 @@ $ make menuconfig **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.3 _Pyro_ and Yocto Project{nbsp}2.4 _Rocko_ +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 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]] === Build from source @@ -1471,10 +1518,14 @@ 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. 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. There are a few ways to decrease your probability of losing event records. @@ -1654,7 +1705,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 @@ -7317,7 +7368,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. <>::