X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=2.12%2Flttng-docs-2.12.txt;h=d35756d62ac4d7c64848c49fcc83fdf03dd39d0d;hb=f01d94cfafe668cb2d4544bacc0e885b3854d046;hp=e45ea17069e5efce62220db9adbe3db44bc39368;hpb=b52915bd628f3d62bb7d383a72d6ad752deb5b49;p=lttng-docs.git diff --git a/2.12/lttng-docs-2.12.txt b/2.12/lttng-docs-2.12.txt index e45ea17..d35756d 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, 6 April 2020 +v2.12, 3 November 2023 include::../common/copyright.txt[] @@ -88,7 +88,7 @@ Tracing control:: without having to destroy and reconfigure them with the new man:lttng-clear(1) command. + -This is especially useful to clear a tracing session's tracing data +This is especially useful to clear the tracing data of a tracing session between attempts to reproduce a problem. + See <>. @@ -147,7 +147,8 @@ default; see man:getrlimit(2)). Change this hierarchy to group traces by tracing session name rather than by hostname (+$LTTNG_HOME/lttng-traces/__session__/__host__/__domain__+) with the -new relay daemon's opt:lttng-relayd(8):--group-output-by-session option. +new opt:lttng-relayd(8):--group-output-by-session option of the +relay daemon. + This feature is especially useful if you're tracing two or more hosts, having different hostnames, which share the same tracing session name as @@ -166,9 +167,9 @@ Linux kernel tracing:: Use the resulting event records to identify the bounds of a network reception and link the events that occur in the interim (for example, wake-ups) to a specific network reception instance. You can also -analyze the network stack's latency thanks to those event records. +analyze the latency of the network stack thanks to those event records. -* The `irqaction` structure's `thread` field, which specifies the +* The `thread` field of the `irqaction` structure, which specifies the process to wake up when a threaded interrupt request (IRQ) occurs, is now part of the `lttng_statedump_interrupt` event record. + @@ -184,9 +185,9 @@ the same socket. As of LTTng{nbsp}{revision}, only the x86 architecture is supported since all architectures describe their topologies differently. + -The tracepoint's `architecture` field is statically defined and exists -for all architecture implementations. Analysis tools can therefore -anticipate the event record's layout. +The `architecture` field of the tracepoint is statically defined and +exists for all architecture implementations. Analysis tools can +therefore anticipate the layout of the event record. + Event record example: + @@ -294,7 +295,7 @@ Excluding proprietary solutions, a few competing software tracers exist for Linux: https://github.com/dtrace4linux/linux[dtrace4linux]:: - A port of Sun Microsystems's DTrace to Linux. + A port of Sun Microsystems' DTrace to Linux. + The cmd:dtrace tool interprets user scripts and is responsible for loading code into the Linux kernel for further execution and collecting @@ -319,7 +320,8 @@ https://perf.wiki.kernel.org/[perf]:: performance counters, tracepoints, as well as other counters and types of probes. + -perf's controlling utility is the cmd:perf command line/text UI tool. +The controlling utility of perf is the cmd:perf command line/text UI +tool. http://linux.die.net/man/1/strace[strace]:: A command-line utility which records system calls made by a @@ -332,18 +334,18 @@ fulfill its function. http://www.sysdig.org/[sysdig]:: Like SystemTap, uses scripts to analyze Linux kernel events. + -You write scripts, or _chisels_ in sysdig's jargon, in Lua and sysdig -executes them while it traces the system or afterwards. sysdig's -interface is the cmd:sysdig command-line tool as well as the text -UI-based cmd:csysdig tool. +You write scripts, or _chisels_ in the jargon of sysdig, in Lua and +sysdig executes them while it traces the system or afterwards. The +interface of sysdig is the cmd:sysdig command-line tool as well as the +text UI-based cmd:csysdig tool. https://sourceware.org/systemtap/[SystemTap]:: A Linux kernel and user space tracer which uses custom user scripts to produce plain text traces. + SystemTap converts the scripts to the C language, and then compiles them -as Linux kernel modules which are loaded to produce trace data. -SystemTap's primary user interface is the cmd:stap command-line tool. +as Linux kernel modules which are loaded to produce trace data. The +primary user interface of SystemTap is the cmd:stap command-line tool. The main distinctive features of LTTng is that it produces correlated kernel and user space traces, as well as doing so with the lowest @@ -396,35 +398,117 @@ but note that: * You only need to install LTTng-UST if you intend to trace user applications. -[IMPORTANT] -==== -As of 1 April 2020, LTTng{nbsp}{revision} isn't available -as distribution packages, except for <>. +[role="growable"] +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 3{nbsp}November{nbsp}2023. +|==== +|Distribution |Available in releases -<> -to install and use it. -==== +|https://www.ubuntu.com/[Ubuntu] +|Ubuntu{nbsp}16.04 _Xenial Xerus_, Ubuntu{nbsp}18.04 _Bionic Beaver_, +Ubuntu{nbsp}20.04 _Focal Fossa_, and Ubuntu{nbsp}22.04 _Jammy Jellyfish_: +<>. + +|https://www.debian.org/[Debian] +|<>. + +|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://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_]. +|==== + + +[[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_, +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: + +. Add the LTTng Stable{nbsp}{revision} PPA repository and update the + list of packages: ++ +-- +[role="term"] +---- +# apt-add-repository ppa:lttng/stable-2.12 +# 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 +---- +-- -[[arch-linux]] -=== Arch Linux -LTTng-UST{nbsp}{revision} is available in Arch Linux's _community_ -repository, while LTTng-tools{nbsp}{revision} and -LTTng-modules{nbsp}{revision} are available in the -https://aur.archlinux.org/[AUR]. +[[debian]] +=== Debian -To install LTTng{nbsp}{revision} on Arch Linux, using -https://github.com/Jguer/yay[yay] for the AUR packages: +To install LTTng{nbsp}{revision} on Debian{nbsp}11 _bullseye_: . Install the main LTTng{nbsp}{revision} packages: + -- [role="term"] ---- -# pacman -Sy lttng-ust -$ yay -Sy lttng-tools -$ yay -Sy lttng-modules +# 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 ---- -- @@ -434,19 +518,101 @@ $ yay -Sy lttng-modules -- [role="term"] ---- -# pacman -Sy python-lttngust -# pacman -Sy python2-lttngust +# apt-get install python3-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.13, Alpine Linux{nbsp}3.14, +or Alpine Linux{nbsp}3.15: + +. Add the LTTng packages: ++ +-- +[role="term"] +---- +# apk add lttng-tools +# apk add lttng-ust-dev ---- -- +. 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.12.tar.bz2 && +tar -xf lttng-modules-latest-2.12.tar.bz2 && +cd lttng-modules-2.12.* && +make && +sudo make modules_install && +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 To build and install LTTng{nbsp}{revision} from source: -. Using your distribution's package manager, or from source, install - the following dependencies of LTTng-tools and LTTng-UST: +. Using the package manager of your distribution, or from source, + install the following dependencies of LTTng-tools and LTTng-UST: + -- * https://sourceforge.net/projects/libuuid/[libuuid] @@ -798,7 +964,7 @@ $ gcc -o hello hello.o hello-tp.o -llttng-ust -ldl Here's the whole build process: [role="img-100"] -.User space tracing tutorial's build steps. +.Build steps of the user space tracing tutorial. image::ust-flow.png[] To trace the user application: @@ -830,8 +996,8 @@ $ lttng-sessiond --daemonize ---- -- + -Note that a session daemon might already be running, for example as -a service that the distribution's service manager started. +Note that a session daemon might already be running, for example as a +service that the service manager of the distribution started. . List the available user space tracepoints: + @@ -927,7 +1093,7 @@ https://diamon.org/ctf/[CTF]. http://tracecompass.org/[Trace Compass]:: A graphical user interface for viewing and analyzing any type of - logs or traces, including LTTng's. + 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 @@ -1017,7 +1183,7 @@ def top5proc(): if type(msg) is not bt2._EventMessageConst: continue - # Event message's event. + # Event of the event message. event = msg.event # Keep only `sched_switch` events. @@ -1035,7 +1201,7 @@ def top5proc(): # We start here. last_ts = cur_ts - # Previous task command's (short) name. + # (Short) name of the previous task command. prev_comm = str(event.payload_field['prev_comm']) # Initialize an entry in our dictionary if not yet done. @@ -1146,11 +1312,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. @@ -1158,11 +1324,11 @@ Snapshot mode:: LTTng doesn't write the traces by default. + Instead, you can request LTTng to <>, -that is, a copy of the tracing session's current sub-buffers, and to -write it to the target's file system or to send it over the network to a -<> running on a remote system. +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 <>. @@ -1262,9 +1428,9 @@ user ``running'' the kernel. ==== Overwrite vs. discard event record loss modes When an event occurs, LTTng records it to a specific sub-buffer (yellow -arc in the following animations) of a specific channel's ring buffer. -When there's no space left in a sub-buffer, the tracer marks it as -consumable (red) and another, empty sub-buffer starts receiving the +arc in the following animations) of the ring buffer of a specific +channel. When there's no space left in a sub-buffer, the tracer marks it +as consumable (red) and another, empty sub-buffer starts receiving the following event records. A <> eventually consumes the marked sub-buffer (returns to white). @@ -1282,10 +1448,10 @@ record the following events. By default, LTTng-modules and LTTng-UST are _non-blocking_ tracers: when no empty sub-buffer is available, it is acceptable to lose event records when the alternative would be to cause substantial delays in the -instrumented application's execution. LTTng privileges performance over -integrity; it aims at perturbing the target system as little as possible -in order to make tracing of subtle race conditions and rare interrupt -cascades possible. +execution of the instrumented application. LTTng privileges performance +over integrity; it aims at perturbing the target system as little as +possible in order to make tracing of subtle race conditions and rare +interrupt cascades possible. Since LTTng{nbsp}2.10, the LTTng user space tracer, LTTng-UST, supports a _blocking mode_. See the <> to learn how to use the blocking mode. When it comes to losing event records because no empty sub-buffer is available, or because the <> is -reached, the channel's _event record loss mode_ determines what to do. -The available event record loss modes are: +reached, the _event record loss mode_ of the channel determines what to +do. The available event record loss modes are: Discard mode:: Drop the newest event records until the tracer releases a sub-buffer. @@ -1320,13 +1486,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 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. +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. @@ -1361,7 +1532,7 @@ other sub-buffers are left unaltered. since the risk of losing event records is low. + Because events occur less frequently, the sub-buffer switching frequency -should remain low and thus the tracer's overhead shouldn't be a +should remain low and thus the overhead of the tracer shouldn't be a problem. * **Low memory system**: If your target system has a low memory @@ -1391,10 +1562,10 @@ following configurations have the same ring buffer total size: * **Two sub-buffers of 4{nbsp}MiB each**: Expect a very low sub-buffer switching frequency, but if a sub-buffer overwrite happens, half of the event records so far (4{nbsp}MiB) are definitely lost. -* **Eight sub-buffers of 1{nbsp}MiB each**: Expect four times the tracer's - overhead as the previous configuration, but if a sub-buffer - overwrite happens, only the eighth of event records so far are - definitely lost. +* **Eight sub-buffers of 1{nbsp}MiB each**: Expect four times the + overhead of the tracer as the previous configuration, but if a + sub-buffer overwrite happens, only the eighth of event records so far + are definitely lost. In discard mode, the sub-buffers count parameter is pointless: use two sub-buffers and set their size according to the requirements of your @@ -1430,27 +1601,27 @@ normally low. By default, the LTTng tracers use a notification mechanism to signal a full sub-buffer so that a consumer daemon can consume it. When such notifications must be avoided, for example in real-time applications, -use the channel's _read timer_ instead. When the read timer fires, the -<> checks for full, consumable +use the _read timer_ of the channel instead. When the read timer fires, +the <> checks for full, consumable sub-buffers. [[tracefile-rotation]] ==== Trace file count and size -By default, trace files can grow as large as needed. Set the -maximum size of each trace file that a channel writes when you -<>. When the size of -a trace file reaches the channel's fixed maximum size, LTTng creates +By default, trace files can grow as large as needed. Set the maximum +size of each trace file that a channel writes when you +<>. When the size of a +trace file reaches the fixed maximum size of the channel, LTTng creates another file to contain the next event records. LTTng appends a file count to each trace file name in this case. If you set the trace file size attribute when you create a channel, the maximum number of trace files that LTTng creates is _unlimited_ by default. To limit them, set a maximum number of trace files. When the -number of trace files reaches the channel's fixed maximum count, the -oldest trace file is overwritten. This mechanism is called _trace file -rotation_. +number of trace files reaches the fixed maximum count of the channel, +the oldest trace file is overwritten. This mechanism is called _trace +file rotation_. [IMPORTANT] ==== @@ -1480,21 +1651,21 @@ 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 -in one of the attached channel's sub-buffers. +in one of the sub-buffers of the attached channel. The available conditions, as of LTTng{nbsp}{revision}, are: * The event rule _is enabled_. -* The instrumentation point's type _is{nbsp}T_. -* The instrumentation point's name (sometimes called _event name_) +* The type of the instrumentation point _is{nbsp}T_. +* The name of the instrumentation point (sometimes called _event name_) _matches{nbsp}N_, but _isn't{nbsp}E_. -* The instrumentation point's log level _is as severe as{nbsp}L_, or +* The log level of the instrumentation point _is as severe as{nbsp}L_, or _is exactly{nbsp}L_. -* The fields of the event's payload _satisfy_ a filter +* The fields of the payload of the event _satisfy_ a filter expression{nbsp}__F__. As you can see, all the conditions but the dynamic filter are related to -the event rule's status or to the instrumentation point, not to the +the status of the event rule or to the instrumentation point, not to the occurring events. This is why, without a filter, checking if an event passes an event rule isn't a dynamic task: when you create or modify an event rule, all the tracers of its tracing domain enable or disable the @@ -1521,11 +1692,11 @@ 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 occurrence of an event, -like record the event's payload to a buffer. +like record the payload of the event to a buffer. An **event record** is the representation of an event in a sub-buffer. A tracer is responsible for capturing the payload of an event, current -context variables, the event's ID, and the event's timestamp. LTTng +context variables, the ID of the event, and its timestamp. LTTng can append this sub-buffer to a trace file. An **event rule** is a set of conditions which must _all_ be satisfied @@ -1619,7 +1790,7 @@ image::plumbing-liblttng-ctl.png[] The _LTTng control library_, `liblttng-ctl`, is used to communicate with a <> using a C API that hides the -underlying protocol's details. `liblttng-ctl` is part of LTTng-tools. +underlying details of the protocol. `liblttng-ctl` is part of LTTng-tools. The <> is linked with `liblttng-ctl`. @@ -1700,9 +1871,9 @@ Both agents use the same mechanism to trace the log statements. When an agent initializes, it creates a log handler that attaches to the root logger. The agent also registers to a <>. When the application executes a log statement, the root logger passes it -to the agent's log handler. The agent's log handler calls a native -function in a tracepoint provider package shared library linked with -<>, passing the formatted log message and +to the log handler of the agent. The log handler of the agent calls a +native function in a tracepoint provider package shared library linked +with <>, passing the formatted log message and other fields, like its logger name and its log level. This native function contains a user space instrumentation point, hence tracing the log statement. @@ -1862,7 +2033,7 @@ You don't start a consumer daemon manually: a consumer daemon is always spawned by a <> as soon as you create an <>, that is, before you start tracing. When you kill its owner session daemon, the consumer daemon also exits because it is -the session daemon's child process. Command-line options of +the child process of the session daemon. Command-line options of man:lttng-sessiond(8) target the consumer daemon process. There are up to two running consumer daemons per Unix user, whereas only @@ -1916,7 +2087,7 @@ There are many examples of tracing and monitoring in our everyday life: All the previous examples have something in common: they rely on **instruments**. Without the electrodes attached to the surface of your -body's skin, cardiac monitoring is futile. +body skin, cardiac monitoring is futile. LTTng, as a tracer, is no different from those real life examples. If you're about to trace a software system or, in other words, record its @@ -1925,15 +2096,15 @@ subject you're tracing, that is, the actual software. Various ways were developed to instrument a piece of software for LTTng tracing. The most straightforward one is to manually place -instrumentation points, called _tracepoints_, in the software's source -code. It is also possible to add instrumentation points dynamically in -the Linux kernel <>. +instrumentation points, called _tracepoints_, in the source code of the +software. It is also possible to add instrumentation points dynamically +in the Linux kernel <>. If you're only interested in tracing the Linux kernel, your -instrumentation needs are probably already covered by LTTng's built-in -<>. You may also wish to trace a -user application which is already instrumented for LTTng tracing. -In such cases, skip this whole section and read the topics of +instrumentation needs are probably already covered by the built-in +<> of LTTng. You may also wish +to trace a user application which is already instrumented for LTTng +tracing. In such cases, skip this whole section and read the topics of the <> section. Many methods are available to instrument a piece of software for LTTng @@ -1957,7 +2128,7 @@ the <>, `liblttng-ust`, is: . <>. . <>. + the source code of the application>>. . <>. @@ -1977,8 +2148,8 @@ A _tracepoint provider_ is a set of compiled functions which provide supported by LTTng-UST. Those functions can emit events with user-defined fields and serialize those events as event records to one or more LTTng-UST <> sub-buffers. The `tracepoint()` -macro, which you <>, calls those functions. +macro, which you <>, calls those functions. A _tracepoint provider package_ is an object file (`.o`) or a shared library (`.so`) which contains one or more tracepoint providers. @@ -2060,7 +2231,7 @@ A _tracepoint definition_ defines, for a given tracepoint: * Its **input arguments**. They are the macro parameters that the `tracepoint()` macro accepts for this particular tracepoint - in the user application's source code. + in the source code of the user application. * Its **output event fields**. They are the sources of event fields that form the payload of any event that the execution of the `tracepoint()` macro emits for this particular tracepoint. @@ -2105,7 +2276,7 @@ Replace: This tracepoint emits events named `provider_name:tracepoint_name`. [IMPORTANT] -.Event name's length limitation +.Event name length limitation ==== The concatenation of the tracepoint provider name and the tracepoint name must not exceed **254{nbsp}characters**. If it does, the @@ -2154,9 +2325,9 @@ one event field. Each `ctf_*()` macro takes an _argument expression_ parameter. This is a C expression that the tracer evalutes at the `tracepoint()` macro site -in the application's source code. This expression provides a field's -source of data. The argument expression can include input argument names -listed in the `TP_ARGS()` macro. +in the source code of the application. This expression provides the +source of data of a field. The argument expression can include input +argument names listed in the `TP_ARGS()` macro. Each `ctf_*()` macro also takes a _field name_ parameter. Field names must be unique within a given tracepoint definition. @@ -2190,7 +2361,7 @@ TRACEPOINT_EVENT( ---- Refer to this tracepoint definition with the `tracepoint()` macro in -your application's source code like this: +the source code of your application like this: [source,c] ---- @@ -2438,11 +2609,12 @@ holding more than one tracepoint providers. [[probing-the-application-source-code]] -==== Add tracepoints to an application's source code +==== Add tracepoints to the source code of an application -Once you <>, -use the `tracepoint()` macro in your application's source code to insert -the tracepoints that this header <>. +Once you <>, use +the `tracepoint()` macro in the source code of your application to +insert the tracepoints that this header +<>. The `tracepoint()` macro takes at least two parameters: the tracepoint provider name and the tracepoint name. The corresponding tracepoint @@ -2474,10 +2646,10 @@ TRACEPOINT_EVENT( ---- Refer to this tracepoint definition with the `tracepoint()` macro in -your application's source code like this: +the source code of your application like this: [source,c] -.Application's source file. +.Application source file. ---- #include "tp.h" @@ -2489,7 +2661,7 @@ int main(int argc, char* argv[]) } ---- -Note how the application's source code includes +Note how the source code of the application includes the tracepoint provider header file containing the tracepoint definitions to use, path:{tp.h}. ==== @@ -2532,10 +2704,10 @@ TRACEPOINT_EVENT( ---- Refer to this tracepoint definition with the `tracepoint()` macro in -your application's source code like this: +the source code of your application like this: [source,c] -.Application's source file. +.Application source file. ---- #define TRACEPOINT_DEFINE #include "tp.h" @@ -2557,7 +2729,7 @@ it should look like this: .Event record fields |==== -|Field's name |Field's value +|Field name |Field value |`my_constant_field` |40 |`my_int_arg_field` |23 |`my_int_arg_field2` |529 @@ -2634,7 +2806,7 @@ In the following diagrams, we use the following file names: Executable application. `app.o`:: - Application's object file. + Application object file. `tpp.o`:: Tracepoint provider package object file. @@ -3713,8 +3885,8 @@ sudo ldconfig ---- -- -. Using your distribution's package manager, or from source, install - the following 32-bit versions of the following dependencies of +. Using the package manager of your distribution, or from source, + install the following 32-bit versions of the following dependencies of LTTng-tools and LTTng-UST: + -- @@ -3850,8 +4022,8 @@ To use `tracef()` in your application: ---- -- -. In the application's source code, use `tracef()` like you would use - man:printf(3): +. In the source code of the application, use `tracef()` like you would + use man:printf(3): + -- [source,c] @@ -3900,10 +4072,10 @@ super simple, albeit with notable disadvantages compared to using your own format string. This also means that you can't filter events with a custom expression at run time because there are no isolated fields. -* Since `tracef()` uses the C standard library's man:vasprintf(3) - function behind the scenes to format the strings at run time, its - expected performance is lower than with user-defined tracepoints, - which don't require a conversion to a string. +* Since `tracef()` uses the man:vasprintf(3) function of the + C{nbsp}standard library behind the scenes to format the strings at run + time, its expected performance is lower than with user-defined + tracepoints, which don't require a conversion to a string. Taking this into consideration, `tracef()` is useful for some quick prototyping and debugging, but you shouldn't consider it for any @@ -3933,8 +4105,8 @@ To use `tracelog()` in your application: ---- -- -. In the application's source code, use `tracelog()` like you would use - man:printf(3), except for the first parameter which is the log +. In the source code of the application, use `tracelog()` like you would + use man:printf(3), except for the first parameter which is the log level: + -- @@ -4088,7 +4260,7 @@ The LTTng-UST function tracing helpers, path:{liblttng-ust-cyg-profile.so} and path:{liblttng-ust-cyg-profile-fast.so}, take advantage of this feature to add tracepoints to the two generated functions (which contain -`cyg_profile` in their names, hence the helper's name). +`cyg_profile` in their names, hence the name of the helper). To use the LTTng-UST function tracing helper, the source files to instrument must be built using the `-finstrument-functions` compiler @@ -4171,8 +4343,8 @@ with OpenJDK{nbsp}7. To use the LTTng-UST Java agent in a Java application which uses `java.util.logging` (JUL): -. In the Java application's source code, import the LTTng-UST - log handler package for `java.util.logging`: +. In the source code of the Java application, import the LTTng-UST log + handler package for `java.util.logging`: + -- [source,java] @@ -4217,9 +4389,9 @@ lttngUstLogHandler.close(); -- + This isn't strictly necessary, but it is recommended for a clean -disposal of the handler's resources. +disposal of the resources of the handler. -. Include the LTTng-UST Java agent's common and JUL-specific JAR files, +. Include the common and JUL-specific JAR files of the LTTng-UST Java agent, path:{lttng-ust-agent-common.jar} and path:{lttng-ust-agent-jul.jar}, in the https://docs.oracle.com/javase/tutorial/essential/environment/paths.html[class @@ -4311,7 +4483,7 @@ application using `java.util.logging` is named `lttng_jul:event` and has the following fields: `msg`:: - Log record's message. + Log record message. `logger_name`:: Logger name. @@ -4344,8 +4516,8 @@ or a specific JUL log level. To use the LTTng-UST Java agent in a Java application which uses Apache log4j{nbsp}1.2: -. In the Java application's source code, import the LTTng-UST - log appender package for Apache log4j: +. In the source code of the Java application, import the LTTng-UST log + appender package for Apache log4j: + -- [source,java] @@ -4389,10 +4561,10 @@ lttngUstLogAppender.close(); -- + This isn't strictly necessary, but it is recommended for a clean -disposal of the appender's resources. +disposal of the resources of the appender. -. Include the LTTng-UST Java agent's common and log4j-specific JAR - files, path:{lttng-ust-agent-common.jar} and +. Include the common and log4j-specific JAR + files of the LTTng-UST Java agent, path:{lttng-ust-agent-common.jar} and path:{lttng-ust-agent-log4j.jar}, in the https://docs.oracle.com/javase/tutorial/essential/environment/paths.html[class path] when you build the Java application. @@ -4484,7 +4656,7 @@ application using log4j is named `lttng_log4j:event` and has the following fields: `msg`:: - Log record's message. + Log record message. `logger_name`:: Logger name. @@ -4533,7 +4705,7 @@ the JUL or log4j <>. To provide application-specific context fields in a Java application: -. In the Java application's source code, import the LTTng-UST +. In the source code of the Java application, import the LTTng-UST Java agent context classes and interfaces: + -- @@ -4603,7 +4775,7 @@ cim.unregisterContextInfoRetriever("retrieverName"); -- + This isn't strictly necessary, but it is recommended for a clean -disposal of some manager's resources. +disposal of some resources of the manager. . Build your Java application with LTTng-UST Java agent support as usual, following the procedure for either the <> or @@ -4744,8 +4916,8 @@ image::python-app.png[] To use the LTTng-UST Python agent: -. In the Python application's source code, import the LTTng-UST Python - agent: +. In the source code of the Python application, import the LTTng-UST + Python agent: + -- [source,python] @@ -4836,7 +5008,7 @@ application is named `lttng_python:event` and has the following fields: Logging time (string). `msg`:: - Log record's message. + Log record message. `logger_name`:: Logger name. @@ -4970,7 +5142,7 @@ $ lttng view === LTTng kernel tracepoints NOTE: This section shows how to _add_ instrumentation points to the -Linux kernel. The kernel's subsystems are already thoroughly +Linux kernel. The subsystems of the kernel are already thoroughly instrumented at strategic places for LTTng when you <> the <> package. @@ -5025,7 +5197,7 @@ To add an LTTng layer over an existing ftrace tracepoint: + Confirm that the tracepoints exist by looking for their names in the dir:{/sys/kernel/debug/tracing/events/subsys} directory, where `subsys` -is your subsystem's name. +is your subsystem name. . Get a copy of the latest LTTng-modules{nbsp}{revision}: + @@ -5062,7 +5234,7 @@ Start with this template: LTTNG_TRACEPOINT_EVENT( /* - * Format is identical to TRACE_EVENT()'s version for the three + * Format is identical to the TRACE_EVENT() version for the three * following macro parameters: */ my_subsys_my_event, @@ -5084,13 +5256,13 @@ LTTNG_TRACEPOINT_EVENT( + The entries in the `TP_FIELDS()` section are the list of fields for the LTTng tracepoint. This is similar to the `TP_STRUCT__entry()` part of -ftrace's `TRACE_EVENT()` macro. +the `TRACE_EVENT()` ftrace macro. + See <> for a complete description of the available `ctf_*()` macros. -. Create the LTTng-modules probe's kernel module C source file, - +probes/lttng-probe-__subsys__.c+, where +__subsys__+ is your +. Create the kernel module C{nbsp}source file of the LTTng-modules + probe, +probes/lttng-probe-__subsys__.c+, where +__subsys__+ is your subsystem name: + -- @@ -5153,7 +5325,7 @@ $ make KERNELDIR=/path/to/linux -- + Replace `/path/to/linux` with the path to the Linux source tree where -you defined and used tracepoints with ftrace's `TRACE_EVENT()` macro. +you defined and used tracepoints with the `TRACE_EVENT()` ftrace macro. Note that you can also use the <> @@ -5310,7 +5482,7 @@ To unload the loaded probe modules: ---- -- + -You can also use man:modprobe(8)'s `--remove` option if the session +You can also use the man:modprobe(8) `--remove` option if the session daemon terminates abnormally. @@ -5412,7 +5584,7 @@ $ lttng create ---- -- -The created tracing session's name is `auto` followed by the +The name of the created tracing session is `auto` followed by the creation date. To create a tracing session with a specific name: @@ -5428,7 +5600,8 @@ $ lttng create my-session + Replace `my-session` with the specific tracing session name. -LTTng appends the creation date to the created tracing session's name. +LTTng appends the creation date to the name of the created tracing +session. LTTng writes the traces of a tracing session in +$LTTNG_HOME/lttng-trace/__name__+ by default, where +__name__+ is the @@ -5532,8 +5705,8 @@ logger names. To list the available instrumentation points: -* Use the man:lttng-list(1) command with the requested tracing domain's - option amongst: +* Use the man:lttng-list(1) command with the option of the requested + tracing domain amongst: + -- opt:lttng-list(1):--kernel:: @@ -5857,7 +6030,8 @@ $ lttng status To get the status of any tracing session: -* Use the man:lttng-list(1) command with the tracing session's name: +* Use the man:lttng-list(1) command with the name of the tracing + session: + -- [role="term"] @@ -5866,7 +6040,7 @@ $ lttng list my-session ---- -- + -Replace `my-session` with the desired tracing session's name. +Replace `my-session` with the desired tracing session name. [[basic-tracing-session-control]] @@ -6050,7 +6224,8 @@ env:LTTNG_UST_ALLOW_BLOCKING environment variable. |+--output=__TYPE__+ (Linux kernel tracing domain only) | -Set the channel's output type to +__TYPE__+, either `mmap` or `splice`. +Set the output type of the channel to +__TYPE__+, either `mmap` or +`splice`. |==== @@ -6307,7 +6482,7 @@ domain has three. For a given event which passes an enabled <> to be recorded, _all_ the attributes of its executing process must be part of -the inclusion sets of the event rule's tracing domain. +the inclusion sets of the tracing domain of the event rule. Add entries to an inclusion set with the man:lttng-track(1) command and remove entries with the man:lttng-untrack(1) command. A process @@ -6540,10 +6715,10 @@ Replace `remote-system` by the host name or IP address of the remote system. See man:lttng-create(1) for the exact URL format. . On the target system, use the man:lttng(1) command-line tool as usual. - When tracing is active, the target's consumer daemon sends sub-buffers - to the relay daemon running on the remote system instead of flushing - them to the local file system. The relay daemon writes the received - packets to the local file system. + When tracing is active, the consumer daemon of the target sends + sub-buffers to the relay daemon running on the remote system instead + of flushing them to the local file system. The relay daemon writes the + received packets to the local file system. The relay daemon writes trace files to +$LTTNG_HOME/lttng-traces/__hostname__/__session__+ by default, where @@ -6613,10 +6788,10 @@ $ babeltrace2 net://localhost ---- You can start the relay daemon on another system. In this case, you need -to specify the relay daemon's URL when you create the tracing session -with the opt:lttng-create(1):--set-url option. You also need to replace -`localhost` in the procedure above with the host name of the system on -which the relay daemon is running. +to specify the URL of the relay daemon when you create the tracing +session with the opt:lttng-create(1):--set-url option. You also need to +replace `localhost` in the procedure above with the host name of the +system on which the relay daemon is running. See man:lttng-create(1) and man:lttng-relayd(8) for the complete list of command-line options. @@ -6682,8 +6857,8 @@ $ lttng snapshot record --name=my-first-snapshot ---- -- + -LTTng writes the current sub-buffers of all the -<>'s channels to +LTTng writes the current sub-buffers of all the channels of the +<> to trace files on the local file system. Those trace files have `my-first-snapshot` in their name. @@ -6712,16 +6887,16 @@ network>>). [[session-rotation]] === Archive the current trace chunk (rotate a tracing session) -The <> shows how to dump -a tracing session's current sub-buffers to the file system or send them -over the network. When you take a snapshot, LTTng doesn't clear the -tracing session's ring buffers: if you take another snapshot immediately +The <> shows how to dump the +current sub-buffers of a tracing session to the file system or send them +over the network. When you take a snapshot, LTTng doesn't clear the ring +buffers of the tracing session: if you take another snapshot immediately after, both snapshots could contain overlapping trace data. Inspired by https://en.wikipedia.org/wiki/Log_rotation[log rotation], _tracing session rotation_ is a feature which appends the content of the ring buffers to what's already on the file system or sent over the -network since the tracing session's creation or since the last +network since the creation of the tracing session or since the last rotation, and then clears those ring buffers to avoid trace data overlaps. @@ -6908,7 +7083,7 @@ used to timestamp <> when tracing. If, once a <> is <>, a major https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction -happens, the trace's clock offset also needs to be updated. Use +happens, the clock offset of the trace also needs to be updated. Use the `metadata` item of the man:lttng-regenerate(1) command to do so. The main use case of this command is to allow a system to boot with @@ -7008,9 +7183,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. @@ -7064,15 +7238,15 @@ $ lttng-crash --extract=/path/to/trace /path/to/shm [role="since-2.10"] [[notif-trigger-api]] -=== Get notified when a channel's buffer usage is too high or too low +=== Get notified when the buffer usage of a channel is too high or too low -With LTTng's $$C/C++$$ notification and trigger API, your user +With the $$C/C++$$ notification and trigger API of LTTng, your user application can get notified when the buffer usage of one or more <> becomes too low or too high. Use this API and enable or disable <> during tracing to avoid <>. -.Have a user application get notified when an LTTng channel's buffer usage is too high. +.Have a user application get notified when the buffer usage of an LTTng channel is too high. ==== In this example, we create and build an application which gets notified when the buffer usage of a specific LTTng channel is higher than @@ -7080,7 +7254,7 @@ when the buffer usage of a specific LTTng channel is higher than could as well use the API of <> to disable event rules when this happens. -. Create the application's C source file: +. Create the C{nbsp}source file of application: + -- [source,c] @@ -7232,8 +7406,8 @@ int main(int argc, char *argv[]) /* * At this point, instead of printing a message, we - * could do something to reduce the channel's buffer - * usage, like disable specific events. + * could do something to reduce the buffer usage of the channel, + * like disable specific events. */ printf("Buffer usage is %f %% in tracing session \"%s\", " "user space channel \"%s\".\n", buffer_usage * 100, @@ -7275,8 +7449,8 @@ $ lttng start -- + If you create the channel manually with the man:lttng-enable-channel(1) -command, control how frequently are the current values of the -channel's properties sampled to evaluate user conditions with the +command, control how frequently LTTng samples the current values of the +channel properties to evaluate user conditions with the opt:lttng-enable-channel(1):--monitor-timer option. . Run the `notif-app` application. This program accepts the @@ -7343,7 +7517,7 @@ The available enumeration entry macros are: +ctf_enum_auto(__name__)+:: Entry named +__name__+ mapped to the integral value following the - last mapping's value. + last mapping value. + The last value of a `ctf_enum_value()` entry is its +__value__+ parameter. @@ -7770,9 +7944,9 @@ clock:: [[def-current-trace-chunk]]current trace chunk:: A <> which includes the current content - of all the <>'s - <> and the stream files produced since the - latest event amongst: + of all the <> of the + <> and the stream files + produced since the latest event amongst: + * The creation of the <>. * The last tracing session rotation, if any. @@ -7789,8 +7963,8 @@ clock:: code, or a Linux kernel kprobe. + An event is said to _occur_ at a specific time. <> can -take various actions upon the occurrence of an event, like record the -event's payload to a <>. +take various actions upon the occurrence of an event, like record its +payload to a <>. [[def-event-name]]event name:: The name of an <>, which is also the name of the @@ -7827,8 +8001,9 @@ instrumentation point name:: See _<>_. `java.util.logging`:: - Java platform's - https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[core logging facilities]. + The + https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[core logging facilities] + of the Java platform. log4j:: A http://logging.apache.org/log4j/1.2/[logging library] for Java