X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=2.7%2Flttng-docs-2.7.txt;h=6d783239a5d4740f257dd5cd28afb447395b7789;hb=146d7451a16a32feeeefe65df794b76eaf9c2ff7;hp=c8f68489032b6189b63cb9c5b7d05941bcb9dc2f;hpb=70feaa74c40db0e51d05bbe3e459ed8065b3f8f5;p=lttng-docs.git diff --git a/2.7/lttng-docs-2.7.txt b/2.7/lttng-docs-2.7.txt index c8f6848..6d78323 100644 --- a/2.7/lttng-docs-2.7.txt +++ b/2.7/lttng-docs-2.7.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.7, 25 October 2016 +v2.7, 24 July 2017 include::../common/copyright.txt[] @@ -289,7 +289,7 @@ becomes inactive or in real-time. [[installing-lttng]] == Installation -include::../common/warning-installation-outdated.txt[] +include::../common/warning-no-installation.txt[] **LTTng** is a set of software <> which interact to <> the Linux kernel and user applications, and @@ -305,298 +305,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. -|==== -|Distribution |Available in releases |Alternatives - -|Ubuntu -|<> -|LTTng{nbsp}2.8 for Ubuntu{nbsp}16.10 _Yakkety Yak_. - -LTTng{nbsp}{revision} for Ubuntu{nbsp}12.04 _Precise Pangolin_, -Ubuntu{nbsp}14.04 _Trusty Tahr_, and Ubuntu{nbsp}16.04 _Xenial Xerus_: -<>. - -<> for -other Ubuntu releases. - -|Fedora -|_Not available_ -|LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} for -Fedora{nbsp}25 and Fedora{nbsp}26 (both are not released yet). - -<>. - -<> for -other Fedora releases. - -|Debian -|_Not available_ -|LTTng{nbsp}2.8 for Debian "stretch" (testing). - -<> for -other Debian releases. - -|openSUSE -|<> -|<> for -other openSUSE releases. - -|Arch Linux -|_Not available_ -| -LTTng{nbsp}2.8 on the AUR. - -<>. - -|Alpine Linux -|_Not available_ -|LTTng{nbsp}2.8 for Alpine Linux "edge". - -LTTng{nbsp}2.8 for Alpine Linux{nbsp}3.5 (not released yet). - -<> for -other Alpine Linux releases. - -|RHEL and SLES -|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| - -|Buildroot -|<<"buildroot","Buildroot{nbsp}2016.02, Buildroot{nbsp}2016.05, -and Buildroot{nbsp}2016.08">> -|LTTng{nbsp}2.8 for Buildroot{nbsp}2016.11 (not released yet). - -<> for -other Buildroot releases. - -|OpenEmbedded and Yocto -|<> (`openembedded-core` layer) -|LTTng{nbsp}2.8 for Yocto Project{nbsp}2.2 _Morty_. - -<> for -other Yocto releases. -|==== - - -[[ubuntu]] -=== [[ubuntu-official-repositories]]Ubuntu - -LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.04 _Xenial Xerus_. -For previous releases of Ubuntu, <>. - -To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.04 _Xenial Xerus_: - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -sudo apt-get install lttng-tools -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev ----- --- - -. **If you need to instrument and trace - <>**, install the LTTng-UST - Java agent: -+ --- -[role="term"] ----- -sudo apt-get install liblttng-ust-agent-java ----- --- - -. **If you need to instrument and trace - <>**, install the - LTTng-UST Python agent: -+ --- -[role="term"] ----- -sudo 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}12.04 _Precise Pangolin_ -* 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"] ----- -sudo apt-add-repository ppa:lttng/stable-2.7 -sudo apt-get update ----- --- - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -sudo apt-get install lttng-tools -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev ----- --- - -. **If you need to instrument and trace - <>**, install the LTTng-UST - Java agent: -+ --- -[role="term"] ----- -sudo apt-get install liblttng-ust-agent-java ----- --- - -. **If you need to instrument and trace - <>**, install the - LTTng-UST Python agent: -+ --- -[role="term"] ----- -sudo apt-get install python3-lttngust ----- --- - - -[[opensuse]] -=== noch:{openSUSE}/RPM - -To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}42.1: - -* 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. -==== - - -[[buildroot]] -=== Buildroot - -To install LTTng{nbsp}{revision} on Buildroot{nbsp}2016.02, -Buildroot{nbsp}2016.05, or Buildroot{nbsp}2016.08: - -. 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.1 _Krogoth_ 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. -==== - - -[[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 @@ -1628,7 +1344,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 @@ -1663,7 +1379,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)). @@ -1959,7 +1675,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 @@ -4117,7 +3833,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. @@ -4835,12 +4551,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} ---- # ... @@ -5150,7 +4866,7 @@ To output LTTng traces to a non-default location: -- [role="term"] ---- -lttng create --output=/tmp/some-directory my-session +lttng create my-session --output=/tmp/some-directory ---- -- @@ -6042,7 +5758,7 @@ To use LTTng live: -- [role="term"] ---- -lttng create --live my-session +lttng create my-session --live ---- -- + @@ -6108,7 +5824,7 @@ To take a snapshot: -- [role="term"] ---- -lttng create --snapshot my-session +lttng create my-session --snapshot ---- -- + @@ -6208,7 +5924,7 @@ trace data after a system crash: -- [role="term"] ---- -lttng create --shm-path=/path/to/shm +lttng create my-session -shm-path=/path/to/shm ---- -- @@ -6855,7 +6571,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. <>::