X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.12%2Flttng-docs-2.12.txt;h=5c1cce63fe130568c80e20fa6cff545f36e7a285;hb=2aced17eaed27e378b2b01e6164d7cd40f0f0164;hp=7d8311fadde28c53f8c5e82573c78ff732b5e646;hpb=05bbb80b2fe5f5d07f81c207fdc2b23dcaf150cb;p=lttng-docs.git diff --git a/2.12/lttng-docs-2.12.txt b/2.12/lttng-docs-2.12.txt index 7d8311f..5c1cce6 100644 --- a/2.12/lttng-docs-2.12.txt +++ b/2.12/lttng-docs-2.12.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.12, 14 January 2021 +v2.12, 28 November 2023 include::../common/copyright.txt[] @@ -399,26 +399,33 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 5{nbsp}August{nbsp}2020. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 3{nbsp}November{nbsp}2023. |==== |Distribution |Available in releases |https://www.ubuntu.com/[Ubuntu] |Ubuntu{nbsp}16.04 _Xenial Xerus_, Ubuntu{nbsp}18.04 _Bionic Beaver_, -and Ubuntu{nbsp}20.04 _Focal Fossa_: +Ubuntu{nbsp}20.04 _Focal Fossa_, and Ubuntu{nbsp}22.04 _Jammy Jellyfish_: <>. |https://www.debian.org/[Debian] -|<>. +|<>. -|https://www.archlinux.org/[Arch Linux] -|<>. +|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] +|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. |https://alpinelinux.org/[Alpine Linux] -|<>. +|xref:alpine-linux[Alpine Linux{nbsp}3.12, Alpine Linux{nbsp}3.13, +Alpine Linux{nbsp}3.14, and Alpine Linux{nbsp}3.15]. -|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}2020.08, Buildroot{nbsp}2020.11, +Builroot{nbsp}2021.02, Buildroot{nbsp}2021.05, Buildroot{nbsp}2021.08, +and Builroot{nbsp}2021.11]. + +|https://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and +https://www.yoctoproject.org/[Yocto] +|xref:oe-yocto[Yocto Project{nbsp}3.2 _Gatesgarth_ and Yocto Project{nbsp}3.3 _Hardknott_]. |==== @@ -428,7 +435,8 @@ and Ubuntu{nbsp}20.04 _Focal Fossa_: 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_, -Ubuntu{nbsp}18.04 _Bionic Beaver_, and Ubuntu{nbsp}20.04 _Focal Fossa_. +Ubuntu{nbsp}18.04 _Bionic Beaver_, Ubuntu{nbsp}20.04 _Focal Fossa_, +and Ubuntu{nbsp}22.04 _Jammy Jellyfish_. To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: @@ -481,7 +489,7 @@ PPA: [[debian]] === Debian -To install LTTng{nbsp}{revision} on Debian "bullseye" (testing): +To install LTTng{nbsp}{revision} on Debian{nbsp}11 _bullseye_: . Install the main LTTng{nbsp}{revision} packages: + @@ -514,46 +522,12 @@ To install LTTng{nbsp}{revision} on Debian "bullseye" (testing): ---- -- - -[[arch-linux]] -=== Arch Linux - -LTTng-UST{nbsp}{revision} is available in the _community_ -repository of Arch Linux, while LTTng-tools{nbsp}{revision} and -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/Jguer/yay[yay] for the AUR packages: - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -# pacman -Sy lttng-ust -$ yay -Sy lttng-tools -$ yay -Sy lttng-modules ----- --- - -. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: -+ --- -[role="term"] ----- -# pacman -Sy python-lttngust -# pacman -Sy python2-lttngust ----- --- - - [[alpine-linux]] === Alpine Linux To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on -Alpine Linux{nbsp}3.12: +Alpine Linux{nbsp}3.12, Alpine Linux{nbsp}3.13, Alpine Linux{nbsp}3.14, +or Alpine Linux{nbsp}3.15: . Add the LTTng packages: + @@ -581,6 +555,57 @@ sudo depmod -a -- +[[buildroot]] +=== Buildroot + +To install LTTng{nbsp}{revision} on Buildroot{nbsp}2020.08, Buildroot{nbsp}2020.11, +Buildroot{nbsp}2021.02, Buildroot{nbsp}2021.05, Buildroot{nbsp}2021.08, or +Buildroot{nbsp}2021.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 + +LTTng{nbsp}{revision} recipes are available in the +https://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/[`openembedded-core`] +layer for Yocto Project{nbsp}3.2 _Gatesgarth_ and Yocto Project{nbsp}3.3 _Hardknott_ +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. + + [[building-from-source]] === Build from source @@ -687,6 +712,45 @@ the installed files in a specific directory. This can be useful to test LTTng without installing it on your system. +[[linux-kernel-sig]] +=== Linux kernel module signature + +Linux kernel modules require trusted signatures in order to be loaded +when any of the following is true: + +* The system boots with + https://uefi.org/specs/UEFI/2.10/32_Secure_Boot_and_Driver_Signing.html#secure-boot-and-driver-signing[Secure Boot] + enabled. + +* The Linux kernel which boots is configured with + `CONFIG_MODULE_SIG_FORCE`. + +* The Linux kernel boots with a command line containing + `module.sig_enforce=1`. + +.`root` user running <> which fails to load a required <> due to the signature enforcement policies. +==== +[role="term"] +---- +# lttng-sessiond +Warning: No tracing group detected +modprobe: ERROR: could not insert 'lttng_ring_buffer_client_discard': Key was rejected by service +Error: Unable to load required module lttng-ring-buffer-client-discard +Warning: No kernel tracer available +---- +==== + +There are several methods to enroll trusted keys for signing modules +that are built from source. The precise details vary from one Linux +version to another, and distributions may have their own mechanisms. For +example, https://github.com/dell/dkms[DKMS] may autogenerate a key and +sign modules, but the key isn't automatically enrolled. + +See +https://www.kernel.org/doc/html/latest/admin-guide/module-signing.html[Kernel +module signing facility] and the documentation of your distribution +to learn more about signing Linux kernel modules. + [[getting-started]] == Quick start @@ -1050,7 +1114,7 @@ Once you have completed the <> and <> tutorials, you can inspect the recorded events. -There are many tools you can use to read LTTng traces: +There are tools you can use to read LTTng traces: https://babeltrace.org/[Babeltrace{nbsp}2]:: A rich, flexible trace manipulation toolkit which includes @@ -1070,11 +1134,6 @@ http://tracecompass.org/[Trace Compass]:: A graphical user interface for viewing and analyzing any type of logs or traces, including those of LTTng. -https://github.com/lttng/lttng-analyses[**LTTng analyses**]:: - An experimental project which includes many high-level analyses of - LTTng kernel traces, like scheduling statistics, interrupt - frequency distribution, top CPU usage, and more. - NOTE: This section assumes that LTTng saved the traces it recorded during the previous tutorials to their default location, in the dir:{$LTTNG_HOME/lttng-traces} directory. The env:LTTNG_HOME @@ -1287,11 +1346,11 @@ LTTng can send the generated trace data to different locations. The _tracing session mode_ dictates where to send it. The following modes are available in LTTng{nbsp}{revision}: -Local mode:: +[[local-mode]]Local mode:: LTTng writes the traces to the file system of the machine it traces (target system). -Network streaming mode:: +[[net-streaming-mode]]Network streaming mode:: LTTng sends the traces over the network to a <> running on a remote system. @@ -1303,7 +1362,7 @@ that is, a copy of the current sub-buffers of the tracing session, and to write it to the file system of the target or to send it over the network to a <> running on a remote system. -Live mode:: +[[live-mode]]Live mode:: This mode is similar to the network streaming mode, but a live trace viewer can connect to the distant relay daemon to <>. @@ -1461,14 +1520,18 @@ 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, since LTTng{nbsp}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, LTTng doesn't write to the trace the exact number of lost event -records in those lost sub-buffers. Trace analyses can use saved -discarded event record and sub-buffer counts of the trace to decide -whether or not to perform the analyses even if trace data is known to be -missing. +event record is lost and saves this count to the trace. Since +LTTng{nbsp}2.8, in overwrite mode, LTTng writes to a given sub-buffer +its sequence number within its data stream. With a <>, +<>, or <> +<>, a trace reader can use such +sequence numbers to report lost packets. In overwrite mode, LTTng +doesn't write to the trace the exact number of lost event records in +those lost sub-buffers. + +Trace analyses can use saved discarded event record and sub-buffer +(packet) counts of the trace 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. @@ -1894,8 +1957,9 @@ See <>. Generally, you don't have to load the LTTng kernel modules manually (using man:modprobe(8), for example): a root <> loads the necessary modules when starting. If you have extra -probe modules, you can specify to load them to the session daemon on -the command line. +probe modules, you can specify to load them to the session daemon on the +command line. See also +<>. The LTTng kernel modules are installed in +/usr/lib/modules/__release__/extra+ by default, where +__release__+ is @@ -7154,9 +7218,8 @@ structures in RAM and retrieve them after a reboot, without flushing to typical _storage_. Linux supports NVRAM file systems thanks to either -http://pramfs.sourceforge.net/[PRAMFS] or https://www.kernel.org/doc/Documentation/filesystems/dax.txt[DAX]{nbsp}+{nbsp}http://lkml.iu.edu/hypermail/linux/kernel/1504.1/03463.html[pmem] -(requires Linux{nbsp}4.1+). +(requires Linux{nbsp}4.1+) or http://pramfs.sourceforge.net/[PRAMFS] (requires Linux{nbsp}<{nbsp}4). This section doesn't describe how to operate such file systems; we assume that you have a working persistent memory file system. @@ -7993,11 +8056,6 @@ log level:: project which you can use to send and receive control messages to and from a <>. -LTTng analyses:: - The https://github.com/lttng/lttng-analyses[LTTng analyses] project, - which is a set of analyzing programs that you can use to obtain a - higher level view of an <> <>. - cmd:lttng-consumerd:: The name of the <> program.