X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=2.11%2Flttng-docs-2.11.txt;h=f99a7ca52ac1f68e9b14798a51a496713aa9f373;hb=b52915bd628f3d62bb7d383a72d6ad752deb5b49;hp=d2dc5c23293404b191bdda011026e076d2941667;hpb=0edf0f23f29d9c9435bbe7f2ccd3029902cc49d4;p=lttng-docs.git diff --git a/2.11/lttng-docs-2.11.txt b/2.11/lttng-docs-2.11.txt index d2dc5c2..f99a7ca 100644 --- a/2.11/lttng-docs-2.11.txt +++ b/2.11/lttng-docs-2.11.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.11, 22 October 2019 +v2.11, 6 April 2020 include::../common/copyright.txt[] @@ -170,7 +170,7 @@ when a kernel event occurs. For example: + [role="term"] ---- -$ lttng enable-event --kernel --syscall read +$ lttng enable-event --kernel --syscall open $ lttng add-context --kernel --type=callstack-kernel --type=callstack-user ---- + @@ -202,6 +202,14 @@ address. + This change makes the tracer more efficient on NUMA systems. +* The <> kernel module now also + creates a ``misc'' device named `lttng-logger`, which udev will + make accessible as the path:{/dev/lttng-logger} special file. ++ +The `lttng-logger` device shares the `/proc/lttng-logger` file's ABI, +but it works from within containers when the path is made accessible to +them. + [[nuts-and-bolts]] == Nuts and bolts @@ -298,7 +306,7 @@ exist for Linux: is the de facto function tracer of the Linux kernel. Its user interface is a set of special files in sysfs. * https://perf.wiki.kernel.org/[perf] is - a performance analyzing tool for Linux which supports hardware + a performance analysis tool for Linux which supports hardware performance counters, tracepoints, as well as other counters and types of probes. perf's controlling utility is the cmd:perf command line/curses tool. @@ -371,14 +379,123 @@ but note that: * You only need to install LTTng-UST if you intend to trace user applications. -[IMPORTANT] -==== -As of 22 October 2019, LTTng{nbsp}{revision} is not available -as distribution packages, except for <>. +[role="growable"] +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 30 March 2020. +|==== +|Distribution |Available in releases -You can <> -to install and use it. -==== +|https://www.ubuntu.com/[Ubuntu] +|Ubuntu{nbsp}16.04 _Xenial Xerus_ and Ubuntu{nbsp}18.04 _Bionic Beaver_: +<>. + +|https://www.debian.org/[Debian] +|<>. + +|https://www.archlinux.org/[Arch Linux] +|<>. + +|https://getfedora.org/[Fedora] +|xref:fedora[Fedora{nbsp}32 and Fedora{nbsp}33]. + +|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}2019.11 and Buildroot{nbsp}2020.02]. +|==== + + +[[ubuntu-ppa]] +=== Ubuntu: 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}16.04 _Xenial Xerus_ and +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.11 +# 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 +---- +-- + + +[[debian]] +=== Debian + +To install LTTng{nbsp}{revision} on Debian "bullseye" (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]] @@ -390,7 +507,7 @@ 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/actionless/pikaur[pikaur] for the AUR packages: +https://github.com/Jguer/yay[yay] for the AUR packages: . Install the main LTTng{nbsp}{revision} packages: + @@ -398,8 +515,8 @@ https://github.com/actionless/pikaur[pikaur] for the AUR packages: [role="term"] ---- # pacman -Sy lttng-ust -$ pikaur -Sy lttng-tools -$ pikaur -Sy lttng-modules +$ yay -Sy lttng-tools +$ yay -Sy lttng-modules ---- -- @@ -415,6 +532,77 @@ $ pikaur -Sy lttng-modules -- +[[fedora]] +=== Fedora + +To install LTTng{nbsp}{revision} on Fedora{nbsp}32 and Fedora{nbsp}33: + +. 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.11.tar.bz2 && +tar -xf lttng-modules-latest-2.11.tar.bz2 && +cd lttng-modules-2.11.* && +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. +==== + + +[[buildroot]] +=== Buildroot + +To install LTTng{nbsp}{revision} on Buildroot{nbsp}2019.11 and +Buildroot{nbsp}2020.02: + +. 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 @@ -1158,11 +1346,6 @@ source code), you need to specify a tracing domain when <> because all the tracing domains could have tracepoints with the same names. -Some features are reserved to specific tracing domains. Dynamic function -entry and return instrumentation points, for example, are currently only -supported in the Linux kernel tracing domain, but support for other -tracing domains could be added in the future. - You can create <> in the Linux kernel and user space tracing domains. The other tracing domains have a single default channel. @@ -1271,8 +1454,7 @@ reached, the channel's _event record loss mode_ determines what to do. The available event record loss modes are: Discard mode:: - Drop the newest event records until a the tracer releases a - sub-buffer. + Drop the newest event records until the tracer releases a sub-buffer. + This is the only available mode when you specify a <>. @@ -1452,7 +1634,7 @@ for LTTng to record an occuring event. You set the conditions when you <>. -You always attach an event rule to <> when you create +You always attach an event rule to a <> when you create it. When an event passes the conditions of an event rule, LTTng records it @@ -1612,9 +1794,9 @@ Some objects are referenced by name (C string), such as tracing sessions, but most of them require to create a handle first using `lttng_create_handle()`. -The best available developer documentation for `liblttng-ctl` is, as of -LTTng{nbsp}{revision}, its installed header files. Every function and -structure is thoroughly documented. +As of LTTng{nbsp}{revision}, the best available developer documentation for +`liblttng-ctl` is its installed header files. Every function and structure is +thoroughly documented. [[lttng-ust]] @@ -1719,8 +1901,9 @@ kernel tracer writes to the ring buffer; a * The _LTTng logger_ module. + The LTTng logger module implements the special path:{/proc/lttng-logger} -file so that any executable can generate LTTng events by opening and -writing to this file. +(and path:{/dev/lttng-logger} since LTTng{nbsp}2.11) files so that any +executable can generate LTTng events by opening and writing to those +files. + See <>. @@ -3971,7 +4154,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. @@ -4133,7 +4316,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 @@ -4860,9 +5043,10 @@ variable. === LTTng logger The `lttng-tracer` Linux kernel module, part of -<>, creates the special LTTng logger file -path:{/proc/lttng-logger} when it's loaded. Any application can write -text data to this file to emit an LTTng event. +<>, creates the special LTTng logger files +path:{/proc/lttng-logger} and path:{/dev/lttng-logger} (since +LTTng{nbsp}2.11) when it's loaded. Any application can write text data +to any of those files to emit an LTTng event. [role="img-100"] .An application writes to the LTTng logger file to emit an LTTng event. @@ -4874,7 +5058,7 @@ mostly to instrument shell scripts: [role="term"] ---- -$ echo "Some message, some $variable" > /proc/lttng-logger +$ echo "Some message, some $variable" > /dev/lttng-logger ---- Any event that the LTTng logger emits is named `lttng_logger` and @@ -4886,7 +5070,7 @@ matches its event name, not only the root user or users in the To use the LTTng logger: -* From any application, write text data to the path:{/proc/lttng-logger} +* From any application, write text data to the path:{/dev/lttng-logger} file. The `msg` field of `lttng_logger` event records contains the @@ -4908,9 +5092,9 @@ can be instrumented in a more efficient way, namely: [source,bash] .path:{test.bash} ---- -echo 'Hello, World!' > /proc/lttng-logger +echo 'Hello, World!' > /dev/lttng-logger sleep 2 -df --human-readable --print-type / > /proc/lttng-logger +df --human-readable --print-type / > /dev/lttng-logger ---- <>, @@ -6109,7 +6293,7 @@ help you solve a problem faster. Examples of context fields are: **process priority** of the thread in which the event occurs. * The **hostname** of the system on which the event occurs. * The Linux kernel and user call stacks (since - LTTng{nbsp}{revision}). + LTTng{nbsp}2.11). * The current values of many possible **performance counters** using perf, for example: ** CPU cycles, stalled cycles, idle cycles, and the other cycle types. @@ -6379,8 +6563,8 @@ Replace `my-session` with the name of the tracing session to load. When LTTng loads a configuration, it restores your saved tracing session as if you just configured it manually. -See man:lttng(1) for the complete list of command-line options. You -can also save and load all many sessions at a time, and decide in which +See man:lttng-load(1) for the complete list of command-line options. You +can also save and load many sessions at a time, and decide in which directory to output the XML files.