X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=5a42c473c158eb31ef8595192776abfa04651542;hb=2e333859971dee32131788543efc1261aebf6f14;hp=89235489ddd38f7faec0bb739a2ee42b8c49d561;hpb=af80c5ed0c98022e0ad64cf6380981218948c5a7;p=lttng-docs.git diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt index 8923548..5a42c47 100644 --- a/2.8/lttng-docs-2.8.txt +++ b/2.8/lttng-docs-2.8.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.8, 25 October 2016 +v2.8, 2 December 2016 include::../common/copyright.txt[] @@ -112,9 +112,10 @@ lttng enable-event --log4j my_logger \ + See man:lttng-status(1). -** New `lttng metadata regenerate` command to regenerate the metadata - file of an LTTng trace at any moment. This command is meant to be - used to resample the wall time following a major +** New `lttng metadata regenerate` command to + <> at any moment. This command is meant to be used to resample + the wall time following a major https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction so that a system which boots with an incorrect wall time can be traced before its wall time is NTP-corrected. @@ -371,67 +372,60 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 2 December 2016. |==== |Distribution |Available in releases |Alternatives -|Ubuntu -|<> +|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]. + <> for other Ubuntu releases. -|Fedora -|_Not available_ -|LTTng{nbsp}{revision} for Fedora{nbsp}25 and Fedora{nbsp}26 (not -released yet). - -<> for +|https://getfedora.org/[Fedora] +|<>. +|<> for other Fedora releases. -|Debian -|<> -| -<> for +|https://www.debian.org/[Debian] +|<>. +|<> for previous Debian releases. -|openSUSE +|https://www.opensuse.org/[openSUSE] |_Not available_ -|LTTng{nbsp}2.7 for openSUSE Leap{nbsp}42.1. +|<>. -<> for -other openSUSE releases. - -|Arch Linux -|Latest AUR packages. -| +|https://www.archlinux.org/[Arch Linux] +|_Not available_ +|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR]. -|Alpine Linux -|<> +|https://alpinelinux.org/[Alpine Linux] +|<>. |LTTng{nbsp}{revision} for Alpine Linux{nbsp}3.5 (not released yet). <> for other Alpine Linux releases. -|RHEL and SLES +|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] |See http://packages.efficios.com/[EfficiOS Enterprise Packages]. | -|Buildroot -|_Not available_ -|LTTng{nbsp}{revision} for Buildroot{nbsp}2016.11 (not released yet). - -LTTng{nbsp}2.7 for Buildroot{nbsp}2016.02, Buildroot{nbsp}2016.05, -and Buildroot{nbsp}2016.08. - -<> for +|https://buildroot.org/[Buildroot] +|<>. +|<> for other Buildroot releases. -|OpenEmbedded and Yocto -|<> (`openembedded-core` layer) +|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and +https://www.yoctoproject.org/[Yocto] +|<> (`openembedded-core` layer). |<> for other OpenEmbedded releases. |==== @@ -444,7 +438,7 @@ LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.10 _Yakkety Yak_. For previous releases of Ubuntu, <>. -To install LTTng{nbsp}{revision} on Ubuntu 16.10{nbsp}_Yakkety Yak_: +To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.10 _Yakkety Yak_: . Install the main LTTng{nbsp}{revision} packages: + @@ -469,7 +463,7 @@ sudo apt-get install liblttng-ust-agent-java -- . **If you need to instrument and trace - <>**, install the + <>**, install the LTTng-UST Python agent: + -- @@ -526,7 +520,7 @@ sudo apt-get install liblttng-ust-agent-java -- . **If you need to instrument and trace - <>**, install the + <>**, install the LTTng-UST Python agent: + -- @@ -537,6 +531,54 @@ sudo 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"] +---- +sudo yum install lttng-tools +sudo 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. +==== + + [[debian]] === Debian @@ -577,8 +619,8 @@ sudo apt-get install python3-lttngust [[alpine-linux]] === Alpine Linux -To install LTTng{nbsp}{revision} (tracing control and user space -tracing) on Alpine Linux "edge": +To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on +Alpine Linux "edge": . Make sure your system is https://wiki.alpinelinux.org/wiki/Edge[configured for "edge"]. @@ -623,6 +665,36 @@ sudo depmod -a -- +[[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 @@ -665,14 +737,6 @@ LTTng-UST{nbsp}{revision} from source and pass the ==== -[[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]. - - [[building-from-source]] === Build from source @@ -798,7 +862,7 @@ This tutorial walks you through the steps to: The following command lines start with cmd:sudo because you need root privileges to trace the Linux kernel. You can avoid using cmd:sudo if -your Unix user is a member of the <>. +your Unix user is a member of the <>. . Create a <>: + @@ -2627,7 +2691,7 @@ holding more than one tracepoint providers. Once you <>, you can use the `tracepoint()` macro in your application's source code to insert the tracepoints that this header -<> defines. +<>. The `tracepoint()` macro takes at least two parameters: the tracepoint provider name and the tracepoint name. The corresponding tracepoint @@ -2836,10 +2900,11 @@ In the following diagrams, we use the following file names: `libemon.so`:: User library shared object file. -The red star indicates that this object file is instrumented -(contains code which uses the `tracepoint()` macro). The spring -symbol between the application and a library means the application is -linked with the library at build time. +We use the following symbols in the diagrams of table below: + +[role="img-100"] +.Symbols used in the build scenario diagrams. +image::ust-sit-symbols.png[] We assume that path:{.} is part of the env:LD_LIBRARY_PATH environment variable in the following instructions. @@ -3288,7 +3353,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3375,7 +3440,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3524,7 +3589,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3597,7 +3662,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -4300,10 +4365,8 @@ Assuming no event record is lost, having only the function addresses on entry is enough to create a call graph, since an event record always contains the ID of the CPU that generated it. + -You can use a tool like -https://sourceware.org/binutils/docs/binutils/addr2line.html[cmd:addr2line] -to convert function addresses back to source file names and -line numbers. +You can use a tool like man:addr2line(1) to convert function addresses +back to source file names and line numbers. * **path:{liblttng-ust-cyg-profile.so}** is a more robust variant which also works in use cases where event records might get discarded or @@ -5017,8 +5080,8 @@ Any event that the LTTng logger emits is named `lttng_logger` and belongs to the Linux kernel <>. However, unlike other instrumentation points in the kernel tracing domain, **any Unix user** can <> which -matches its event name, not only the root user or users in the tracing -group. +matches its event name, not only the root user or users in the +<>. To use the LTTng logger: @@ -7276,7 +7339,7 @@ tracer:: <>:: A namespace for event sources. -tracing group:: +<>:: The Unix group in which a Unix user can be to be allowed to trace the Linux kernel.