X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=9ccf4caa8017f6bc9e250bd3f6398c4f08fb0897;hb=HEAD;hp=d20b55d402ebf32584c5e24655cd52471a7cd193;hpb=7a44b9ff51fd7f2e1db4645bf2b1927a802375ed;p=lttng-docs.git diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt index d20b55d..9ccf4ca 100644 --- a/2.8/lttng-docs-2.8.txt +++ b/2.8/lttng-docs-2.8.txt @@ -1,12 +1,15 @@ The LTTng Documentation ======================= Philippe Proulx -v2.8, 8 December 2016 +v2.8, 25 February 2021 include::../common/copyright.txt[] +include::../common/warning-not-maintained.txt[] + + include::../common/welcome.txt[] @@ -91,7 +94,7 @@ New features and changes in LTTng{nbsp}{revision}: -- [role="term"] ---- -lttng add-context --jul --type='$app.retriever:cur_msg_id' +$ lttng add-context --jul --type='$app.retriever:cur_msg_id' ---- -- + @@ -110,7 +113,7 @@ are supported. -- [role="term"] ---- -lttng enable-event --log4j my_logger \ +$ lttng enable-event --log4j my_logger \ --filter='$app.retriever:cur_msg_id == 23' ---- -- @@ -204,7 +207,7 @@ for an overview of the small API. -- [role="term"] ---- -man lttng-enable-event +$ man lttng-enable-event ---- -- + @@ -357,6 +360,8 @@ becomes inactive or in real-time. [[installing-lttng]] == Installation +include::../common/warning-no-installation.txt[] + **LTTng** is a set of software <> which interact to <> the Linux kernel and user applications, and to <> (start and stop @@ -371,380 +376,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 as of 2 December 2016. -|==== -|Distribution |Available in releases |Alternatives - -|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. - -|https://getfedora.org/[Fedora] -|<>. -|<> for -other Fedora releases. - -|https://www.debian.org/[Debian] -|<>. -|<> for -previous Debian releases. - -|https://www.opensuse.org/[openSUSE] -|_Not available_ -|<>. - -|https://www.archlinux.org/[Arch Linux] -|_Not available_ -|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR]. - -|https://alpinelinux.org/[Alpine Linux] -|<>. -|LTTng{nbsp}{revision} for Alpine Linux{nbsp}3.5 (not released yet). - -<> for -other Alpine Linux releases. - -|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] -|See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| - -|https://buildroot.org/[Buildroot] -|<>. -|<> for -other Buildroot releases. - -|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and -https://www.yoctoproject.org/[Yocto] -|<> (`openembedded-core` layer). -|<> for -other OpenEmbedded releases. -|==== - - -[[ubuntu]] -=== [[ubuntu-official-repositories]]Ubuntu - -LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.10 _Yakkety Yak_. -For previous releases of Ubuntu, <>. - -To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.10 _Yakkety Yak_: - -. 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}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.8 -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 ----- --- - - -[[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 - -To install LTTng{nbsp}{revision} on Debian "stretch" (testing): - -. Install the main LTTng{nbsp}{revision} packages: -+ --- -[role="term"] ----- -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev -sudo apt-get install lttng-tools ----- --- - -. **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 ----- --- - - -[[alpine-linux]] -=== Alpine Linux - -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"]. -. Enable the _testing_ repository by uncommenting the corresponding - line in path:{/etc/apk/repositories}. -. Add the LTTng packages: -+ --- -[role="term"] ----- -sudo apk add lttng-tools -sudo apk add lttng-ust-dev ----- --- - -To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support) -on Alpine Linux "edge": - -. Add the vanilla Linux kernel: -+ --- -[role="term"] ----- -apk add linux-vanilla linux-vanilla-dev ----- --- - -. Reboot with the vanilla Linux kernel. -. 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 ----- --- - - -[[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 - -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.2 _Morty_ 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. -==== - [[building-from-source]] === Build from source @@ -766,7 +405,7 @@ To build and install LTTng{nbsp}{revision} from source: -- [role="term"] ---- -cd $(mktemp -d) && +$ 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.* && @@ -781,7 +420,7 @@ sudo depmod -a -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.8.tar.bz2 && tar -xf lttng-ust-latest-2.8.tar.bz2 && cd lttng-ust-2.8.* && @@ -831,7 +470,7 @@ instrumented user application with `liblttng-ust`>>: -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 && tar -xf lttng-tools-latest-2.8.tar.bz2 && cd lttng-tools-2.8.* && @@ -869,9 +508,10 @@ This tutorial walks you through the steps to: [[tracing-the-linux-kernel]] === Trace the Linux kernel -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 <>. +The following command lines start with the `#` prompt because you need +root privileges to trace the Linux kernel. You can also trace the kernel +as a regular user if your Unix user is a member of the +<>. . Create a <> which writes its traces to dir:{/tmp/my-kernel-trace}: @@ -879,7 +519,7 @@ your Unix user is a member of the <>. -- [role="term"] ---- -sudo lttng create my-kernel-session --output=/tmp/my-kernel-trace +# lttng create my-kernel-session --output=/tmp/my-kernel-trace ---- -- @@ -888,8 +528,8 @@ sudo lttng create my-kernel-session --output=/tmp/my-kernel-trace -- [role="term"] ---- -lttng list --kernel -lttng list --kernel --syscall +# lttng list --kernel +# lttng list --kernel --syscall ---- -- @@ -900,8 +540,8 @@ lttng list --kernel --syscall -- [role="term"] ---- -sudo lttng enable-event --kernel sched_switch,sched_process_fork -sudo lttng enable-event --kernel --syscall open,close +# lttng enable-event --kernel sched_switch,sched_process_fork +# lttng enable-event --kernel --syscall open,close ---- -- + @@ -911,7 +551,7 @@ tracepoints (this will generate a lot of data when tracing): -- [role="term"] ---- -sudo lttng enable-event --kernel --all +# lttng enable-event --kernel --all ---- -- @@ -920,7 +560,7 @@ sudo lttng enable-event --kernel --all -- [role="term"] ---- -sudo lttng start +# lttng start ---- -- @@ -1017,7 +657,7 @@ TRACEPOINT_EVENT( -- [role="term"] ---- -gcc -c -I. hello-tp.c +$ gcc -c -I. hello-tp.c ---- -- @@ -1077,7 +717,7 @@ int main(int argc, char *argv[]) -- [role="term"] ---- -gcc -c hello.c +$ gcc -c hello.c ---- -- @@ -1087,7 +727,7 @@ gcc -c hello.c -- [role="term"] ---- -gcc -o hello hello.o hello-tp.o -llttng-ust -ldl +$ gcc -o hello hello.o hello-tp.o -llttng-ust -ldl ---- -- @@ -1104,7 +744,7 @@ To trace the user application: -- [role="term"] ---- -./hello world and beyond +$ ./hello world and beyond ---- -- + @@ -1122,7 +762,7 @@ Press Enter to continue... -- [role="term"] ---- -lttng-sessiond --daemonize +$ lttng-sessiond --daemonize ---- -- + @@ -1134,7 +774,7 @@ a service that the distribution's service manager started. -- [role="term"] ---- -lttng list --userspace +$ lttng list --userspace ---- -- + @@ -1146,7 +786,7 @@ under the `./hello` process. -- [role="term"] ---- -lttng create my-user-space-session +$ lttng create my-user-space-session ---- -- @@ -1156,7 +796,7 @@ lttng create my-user-space-session -- [role="term"] ---- -lttng enable-event --userspace hello_world:my_first_tracepoint +$ lttng enable-event --userspace hello_world:my_first_tracepoint ---- -- @@ -1165,7 +805,7 @@ lttng enable-event --userspace hello_world:my_first_tracepoint -- [role="term"] ---- -lttng start +$ lttng start ---- -- @@ -1177,8 +817,8 @@ lttng start -- [role="term"] ---- -sudo lttng stop -sudo lttng destroy +$ lttng stop +$ lttng destroy ---- -- + @@ -1233,7 +873,7 @@ its path to cmd:babeltrace with no options: [role="term"] ---- -babeltrace ~/lttng-traces/my-user-space-session* +$ babeltrace ~/lttng-traces/my-user-space-session* ---- cmd:babeltrace finds all traces recursively within the given path and @@ -1244,7 +884,7 @@ further filtering: [role="term"] ---- -babeltrace /tmp/my-kernel-trace | grep _switch +$ babeltrace /tmp/my-kernel-trace | grep _switch ---- You can pipe the output of cmd:babeltrace into a tool like man:wc(1) to @@ -1252,7 +892,7 @@ count the recorded events: [role="term"] ---- -babeltrace /tmp/my-kernel-trace | grep _open | wc --lines +$ babeltrace /tmp/my-kernel-trace | grep _open | wc --lines ---- @@ -1354,7 +994,7 @@ Run this script: [role="term"] ---- -python3 top5proc.py /tmp/my-kernel-trace/kernel +$ python3 top5proc.py /tmp/my-kernel-trace/kernel ---- Output example: @@ -1434,11 +1074,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 being traced (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. @@ -1449,7 +1089,7 @@ Snapshot mode:: 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 <> by @@ -1604,10 +1244,19 @@ as soon as a there's no space left for a new event record, whereas in 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, LTTng keeps no information when it overwrites a -sub-buffer before consuming it. +In discard mode, LTTng increments a count of lost event records when an +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. @@ -1632,8 +1281,8 @@ to configure the sub-buffer count and size for them: * **High event throughput**: In general, prefer bigger sub-buffers to lower the risk of losing event records. + -Having bigger sub-buffers also ensures a lower sub-buffer switching -frequency. +Having bigger sub-buffers also ensures a lower +<>. + The number of sub-buffers is only meaningful if you create the channel in overwrite mode: in this case, if a sub-buffer overwrite happens, the @@ -1787,7 +1436,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 @@ -1822,7 +1471,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)). @@ -1870,7 +1519,7 @@ The cmd:lttng tool has a Git-like interface: [role="term"] ---- -lttng +$ lttng ---- The <> section explores the @@ -2118,7 +1767,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 @@ -2959,7 +2608,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -2968,7 +2617,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o tpp.o -llttng-ust -ldl +$ gcc -o app app.o tpp.o -llttng-ust -ldl ---- -- @@ -2979,7 +2628,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -2997,7 +2646,7 @@ To create the tracepoint provider package archive file: -- [role="term"] ---- -gcc -I. -c tpp.c +$ gcc -I. -c tpp.c ---- -- @@ -3006,7 +2655,7 @@ gcc -I. -c tpp.c -- [role="term"] ---- -ar rcs tpp.a tpp.o +$ ar rcs tpp.a tpp.o ---- -- @@ -3026,7 +2675,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3035,7 +2684,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o tpp.a -llttng-ust -ldl +$ gcc -o app app.o tpp.a -llttng-ust -ldl ---- -- @@ -3046,7 +2695,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3075,7 +2724,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3084,7 +2733,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -ltpp +$ gcc -o app app.o -ldl -L. -ltpp ---- -- @@ -3095,7 +2744,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3126,7 +2775,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3135,7 +2784,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl +$ gcc -o app app.o -ldl ---- -- @@ -3147,7 +2796,7 @@ To run the instrumented application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3158,7 +2807,7 @@ To run the instrumented application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3191,7 +2840,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3200,7 +2849,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl +$ gcc -o app app.o -ldl ---- -- @@ -3211,7 +2860,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3243,7 +2892,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3252,7 +2901,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o tpp.o -llttng-ust -ldl +$ gcc -shared -o libemon.so emon.o tpp.o -llttng-ust -ldl ---- -- @@ -3263,7 +2912,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3272,7 +2921,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3283,7 +2932,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3315,7 +2964,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3324,7 +2973,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl -L. -ltpp +$ gcc -shared -o libemon.so emon.o -ldl -L. -ltpp ---- -- @@ -3335,7 +2984,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3344,7 +2993,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3355,7 +3004,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3388,7 +3037,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3397,7 +3046,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl +$ gcc -shared -o libemon.so emon.o -ldl ---- -- @@ -3408,7 +3057,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3417,7 +3066,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3429,7 +3078,7 @@ To run the application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3440,7 +3089,7 @@ To run the application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3475,7 +3124,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3484,7 +3133,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl +$ gcc -shared -o libemon.so emon.o -ldl ---- -- @@ -3495,7 +3144,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3504,7 +3153,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3515,7 +3164,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3549,7 +3198,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3558,7 +3207,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl -L. -ltpp +$ gcc -shared -o libemon.so emon.o -ldl -L. -ltpp ---- -- @@ -3569,7 +3218,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3578,7 +3227,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -lemon +$ gcc -o app app.o -ldl -L. -lemon ---- -- @@ -3589,7 +3238,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3624,7 +3273,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3633,7 +3282,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl +$ gcc -shared -o libemon.so emon.o -ldl ---- -- @@ -3644,7 +3293,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3653,7 +3302,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -lemon +$ gcc -o app app.o -ldl -L. -lemon ---- -- @@ -3664,7 +3313,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3697,7 +3346,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3706,7 +3355,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o -ldl +$ gcc -shared -o libemon.so emon.o -ldl ---- -- @@ -3717,7 +3366,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3726,7 +3375,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3738,7 +3387,7 @@ To run the application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3749,7 +3398,7 @@ To run the application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3781,7 +3430,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3790,7 +3439,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o +$ gcc -shared -o libemon.so emon.o ---- -- @@ -3801,7 +3450,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3810,7 +3459,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o tpp.o -llttng-ust -ldl -L. -lemon +$ gcc -o app app.o tpp.o -llttng-ust -ldl -L. -lemon ---- -- @@ -3821,7 +3470,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3852,7 +3501,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3861,7 +3510,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -Wl,--export-dynamic -o app app.o tpp.o \ +$ gcc -Wl,--export-dynamic -o app app.o tpp.o \ -llttng-ust -ldl ---- -- @@ -3877,7 +3526,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3886,7 +3535,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o +$ gcc -shared -o libemon.so emon.o ---- -- @@ -3897,7 +3546,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- |==== @@ -3936,7 +3585,7 @@ object when starting the application. [role="term"] ---- -LD_PRELOAD=liblttng-ust-fork.so ./my-app +$ LD_PRELOAD=liblttng-ust-fork.so ./my-app ---- If your tracepoint provider package is @@ -3945,7 +3594,7 @@ shared objects in env:LD_PRELOAD: [role="term"] ---- -LD_PRELOAD=liblttng-ust-fork.so:/path/to/tp.so ./my-app +$ LD_PRELOAD=liblttng-ust-fork.so:/path/to/tp.so ./my-app ---- @@ -3959,7 +3608,7 @@ build an application on the command line: [role="term"] ---- -gcc -o my-app my-app.o tp.o $(pkg-config --cflags --libs lttng-ust) +$ gcc -o my-app my-app.o tp.o $(pkg-config --cflags --libs lttng-ust) ---- @@ -3984,7 +3633,7 @@ or LTTng packages: -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/urcu/userspace-rcu-latest-0.9.tar.bz2 && tar -xf userspace-rcu-latest-0.9.tar.bz2 && cd userspace-rcu-0.9.* && @@ -4011,7 +3660,7 @@ sudo ldconfig -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.8.tar.bz2 && tar -xf lttng-ust-latest-2.8.tar.bz2 && cd lttng-ust-2.8.* && @@ -4036,7 +3685,7 @@ relevant 32-bit library paths, for example: [role="term"] ---- -LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32' +$ LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32' ---- ==== @@ -4046,7 +3695,7 @@ LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32' -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 && tar -xf lttng-tools-latest-2.8.tar.bz2 && cd lttng-tools-2.8.* && @@ -4070,7 +3719,7 @@ sudo ldconfig -- [role="term"] ---- -cd $(mktemp -d) && +$ cd $(mktemp -d) && wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 && tar -xf lttng-tools-latest-2.8.tar.bz2 && cd lttng-tools-2.8.* && @@ -4097,9 +3746,9 @@ instrumented 32-bit application: -- [role="term"] ---- -gcc -m32 -c -I. hello-tp.c -gcc -m32 -c hello.c -gcc -m32 -o hello hello.o hello-tp.o \ +$ gcc -m32 -c -I. hello-tp.c +$ gcc -m32 -c hello.c +$ gcc -m32 -o hello hello.o hello-tp.o \ -L/usr/lib32 -L/usr/local/lib32 \ -Wl,-rpath,/usr/lib32,-rpath,/usr/local/lib32 \ -llttng-ust -ldl @@ -4151,7 +3800,7 @@ To use `tracef()` in your application: -- [role="term"] ---- -gcc -o app app.c -llttng-ust +$ gcc -o app app.c -llttng-ust ---- -- @@ -4163,7 +3812,7 @@ To trace the events that `tracef()` calls emit: -- [role="term"] ---- -lttng enable-event --userspace 'lttng_ust_tracef:*' +$ lttng enable-event --userspace 'lttng_ust_tracef:*' ---- -- @@ -4238,7 +3887,7 @@ See man:lttng-ust(3) for a list of available log level names. -- [role="term"] ---- -gcc -o app app.c -llttng-ust +$ gcc -o app app.c -llttng-ust ---- -- @@ -4252,7 +3901,7 @@ _as severe as_ a specific log level: -- [role="term"] ---- -lttng enable-event --userspace 'lttng_ust_tracelog:*' +$ lttng enable-event --userspace 'lttng_ust_tracelog:*' --loglevel=TRACE_WARNING ---- -- @@ -4266,7 +3915,7 @@ _specific log level_: -- [role="term"] ---- -lttng enable-event --userspace 'lttng_ust_tracelog:*' +$ lttng enable-event --userspace 'lttng_ust_tracelog:*' --loglevel-only=TRACE_INFO ---- -- @@ -4275,7 +3924,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. @@ -4305,7 +3954,7 @@ To use a user space tracing helper with any user application: -- [role="term"] ---- -LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app +$ LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app ---- -- + @@ -4314,7 +3963,7 @@ You can preload more than one helper: -- [role="term"] ---- -LD_PRELOAD=liblttng-ust-libc-wrapper.so:liblttng-ust-dl.so my-app +$ LD_PRELOAD=liblttng-ust-libc-wrapper.so:liblttng-ust-dl.so my-app ---- -- @@ -4437,7 +4086,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 @@ -4557,7 +4206,7 @@ Build this example: [role="term"] ---- -javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java +$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java ---- <>, @@ -4566,16 +4215,16 @@ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jar [role="term"] ---- -lttng create -lttng enable-event --jul jello -lttng start +$ lttng create +$ lttng enable-event --jul jello +$ lttng start ---- Run the compiled class: [role="term"] ---- -java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test +$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test ---- <> and inspect the @@ -4583,8 +4232,8 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -4730,7 +4379,7 @@ file): [role="term"] ---- -javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH Test.java +$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH Test.java ---- <>, @@ -4739,16 +4388,16 @@ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jar [role="term"] ---- -lttng create -lttng enable-event --log4j jello -lttng start +$ lttng create +$ lttng enable-event --log4j jello +$ lttng start ---- Run the compiled class: [role="term"] ---- -java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH:. Test +$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH:. Test ---- <> and inspect the @@ -4756,8 +4405,8 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -4961,7 +4610,7 @@ Build this example: [role="term"] ---- -javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java +$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java ---- <> @@ -4970,8 +4619,8 @@ and <> matching the [role="term"] ---- -lttng create -lttng enable-event --jul jello +$ lttng create +$ lttng enable-event --jul jello ---- <> to the @@ -4979,22 +4628,22 @@ JUL channel: [role="term"] ---- -lttng add-context --jul --type='$app.myRetriever:intCtx' -lttng add-context --jul --type='$app.myRetriever:strContext' +$ lttng add-context --jul --type='$app.myRetriever:intCtx' +$ lttng add-context --jul --type='$app.myRetriever:strContext' ---- <>: [role="term"] ---- -lttng start +$ lttng start ---- Run the compiled class: [role="term"] ---- -java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test +$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test ---- <> and inspect the @@ -5002,8 +4651,8 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -5089,16 +4738,16 @@ tracing>>: [role="term"] ---- -lttng create -lttng enable-event --python my-logger -lttng start +$ lttng create +$ lttng enable-event --python my-logger +$ lttng start ---- Run the Python script: [role="term"] ---- -python test.py +$ python test.py ---- <> and inspect the recorded @@ -5106,8 +4755,8 @@ events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -5178,7 +4827,7 @@ mostly to instrument shell scripts: [role="term"] ---- -echo "Some message, some $variable" > /proc/lttng-logger +$ echo "Some message, some $variable" > /proc/lttng-logger ---- Any event that the LTTng logger emits is named `lttng_logger` and @@ -5224,16 +4873,16 @@ df --human-readable --print-type / > /proc/lttng-logger [role="term"] ---- -lttng create -lttng enable-event --kernel lttng_logger -lttng start +$ lttng create +$ lttng enable-event --kernel lttng_logger +$ lttng start ---- Run the Bash script: [role="term"] ---- -bash test.bash +$ bash test.bash ---- <> and inspect the recorded @@ -5241,8 +4890,8 @@ events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -5313,7 +4962,7 @@ is your subsystem's name. -- [role="term"] ---- -cd $(mktemp -d) && +$ 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.* @@ -5405,12 +5054,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} ---- # ... @@ -5428,8 +5077,8 @@ obj-m += lttng-probe-my-subsys.o -- [role="term"] ---- -make KERNELDIR=/path/to/linux -sudo make modules_install +$ make KERNELDIR=/path/to/linux +# make modules_install && depmod -a ---- -- + @@ -5546,7 +5195,7 @@ module: ==== [role="term"] ---- -sudo lttng-sessiond --extra-kmod-probes=my_subsys,usb +# lttng-sessiond --extra-kmod-probes=my_subsys,usb ---- ==== -- @@ -5564,7 +5213,7 @@ To load _only_ a given custom probe kernel module: ==== [role="term"] ---- -sudo lttng-sessiond --kmod-probes=my_subsys,usb +# lttng-sessiond --kmod-probes=my_subsys,usb ---- ==== -- @@ -5576,7 +5225,7 @@ To confirm that a probe module is loaded: -- [role="term"] ---- -lsmod | grep lttng_probe_usb +$ lsmod | grep lttng_probe_usb ---- -- @@ -5587,7 +5236,7 @@ To unload the loaded probe modules: -- [role="term"] ---- -sudo pkill lttng-sessiond +# pkill lttng-sessiond ---- -- + @@ -5649,7 +5298,7 @@ To start a user session daemon: -- [role="term"] ---- -lttng-sessiond --daemonize +$ lttng-sessiond --daemonize ---- -- @@ -5660,7 +5309,7 @@ To start the root session daemon: -- [role="term"] ---- -sudo lttng-sessiond --daemonize +# lttng-sessiond --daemonize ---- -- @@ -5689,7 +5338,7 @@ To create a tracing session with a generated name: -- [role="term"] ---- -lttng create +$ lttng create ---- -- @@ -5703,7 +5352,7 @@ To create a tracing session with a specific name: -- [role="term"] ---- -lttng create my-session +$ lttng create my-session ---- -- + @@ -5723,7 +5372,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 ---- -- @@ -5736,7 +5385,7 @@ To list all the existing tracing sessions for your Unix user: -- [role="term"] ---- -lttng list +$ lttng list ---- -- @@ -5767,7 +5416,7 @@ To change the current tracing session: -- [role="term"] ---- -lttng set-session new-session +$ lttng set-session new-session ---- -- + @@ -5785,7 +5434,7 @@ To destroy the current tracing session: -- [role="term"] ---- -lttng destroy +$ lttng destroy ---- -- @@ -5822,7 +5471,7 @@ To list the available instrumentation points: ==== [role="term"] ---- -lttng list --userspace +$ lttng list --userspace ---- ==== @@ -5830,7 +5479,7 @@ lttng list --userspace ==== [role="term"] ---- -lttng list --kernel --syscall +$ lttng list --kernel --syscall ---- ==== @@ -5934,7 +5583,7 @@ command-line options to create simple to more complex event rules. ==== [role="term"] ---- -lttng enable-event --kernel sched_switch +$ lttng enable-event --kernel sched_switch ---- ==== @@ -5942,7 +5591,7 @@ lttng enable-event --kernel sched_switch ==== [role="term"] ---- -lttng enable-event --kernel --syscall open,write,read,close +$ lttng enable-event --kernel --syscall open,write,read,close ---- ==== @@ -5950,18 +5599,18 @@ lttng enable-event --kernel --syscall open,write,read,close ==== [role="term"] ---- -lttng enable-event --kernel sched_switch --filter='prev_comm == "bash"' +$ lttng enable-event --kernel sched_switch --filter='prev_comm == "bash"' ---- [role="term"] ---- -lttng enable-event --kernel --all \ +$ lttng enable-event --kernel --all \ --filter='$ctx.tid == 1988 || $ctx.tid == 1534' ---- [role="term"] ---- -lttng enable-event --jul my_logger \ +$ lttng enable-event --jul my_logger \ --filter='$app.retriever:cur_msg_id > 3' ---- @@ -5973,7 +5622,7 @@ use man:lttng(1) from a shell. ==== [role="term"] ---- -lttng enable-event --userspace my_app:'*' --loglevel=TRACE_INFO +$ lttng enable-event --userspace my_app:'*' --loglevel=TRACE_INFO ---- IMPORTANT: Make sure to always quote the wildcard character when you @@ -5984,7 +5633,7 @@ use man:lttng(1) from a shell. ==== [role="term"] ---- -lttng enable-event --python my-app.'*' \ +$ lttng enable-event --python my-app.'*' \ --exclude='my-app.module,my-app.hello' ---- ==== @@ -5993,7 +5642,7 @@ lttng enable-event --python my-app.'*' \ ==== [role="term"] ---- -lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN +$ lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN ---- ==== @@ -6001,7 +5650,7 @@ lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN ==== [role="term"] ---- -lttng enable-event --userspace my_app:my_tracepoint --channel=my-channel +$ lttng enable-event --userspace my_app:my_tracepoint --channel=my-channel ---- ==== @@ -6013,8 +5662,8 @@ rules: [role="term"] ---- -lttng enable-event --userspace my_app:my_tracepoint -lttng enable-event --userspace my_app:my_tracepoint \ +$ lttng enable-event --userspace my_app:my_tracepoint +$ lttng enable-event --userspace my_app:my_tracepoint \ --loglevel=TRACE_INFO ---- @@ -6038,7 +5687,7 @@ a _disabled_ event rule. ==== [role="term"] ---- -lttng disable-event --python my-logger +$ lttng disable-event --python my-logger ---- ==== @@ -6046,7 +5695,7 @@ lttng disable-event --python my-logger ==== [role="term"] ---- -lttng disable-event --jul '*' +$ lttng disable-event --jul '*' ---- ==== @@ -6059,7 +5708,7 @@ rules of a given channel. [role="term"] ---- -lttng disable-event --jul --all-events +$ lttng disable-event --jul --all-events ---- ==== @@ -6077,7 +5726,7 @@ parameters, its channels, event rules, and their attributes: -- [role="term"] ---- -lttng status +$ lttng status ---- -- + @@ -6089,7 +5738,7 @@ To get the status of any tracing session: -- [role="term"] ---- -lttng list my-session +$ lttng list my-session ---- -- + @@ -6111,7 +5760,7 @@ To start tracing in the current tracing session: -- [role="term"] ---- -lttng start +$ lttng start ---- -- @@ -6127,7 +5776,7 @@ To stop tracing in the current tracing session: -- [role="term"] ---- -lttng stop +$ lttng stop ---- -- + @@ -6252,7 +5901,7 @@ command-line options to create simple to more complex channels. ==== [role="term"] ---- -lttng enable-channel --kernel my-channel +$ lttng enable-channel --kernel my-channel ---- ==== @@ -6260,7 +5909,7 @@ lttng enable-channel --kernel my-channel ==== [role="term"] ---- -lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \ +$ lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \ --buffers-pid my-channel ---- ==== @@ -6269,7 +5918,7 @@ lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \ ==== [role="term"] ---- -lttng enable-channel --kernel --tracefile-count=8 \ +$ lttng enable-channel --kernel --tracefile-count=8 \ --tracefile-size=4194304 my-channel ---- ==== @@ -6278,7 +5927,7 @@ lttng enable-channel --kernel --tracefile-count=8 \ ==== [role="term"] ---- -lttng enable-channel --userspace --overwrite my-channel +$ lttng enable-channel --userspace --overwrite my-channel ---- ==== @@ -6287,8 +5936,8 @@ two different channels: [role="term"] ---- -lttng enable-event --userspace --channel=my-channel app:tp -lttng enable-event --userspace --channel=other-channel app:tp +$ lttng enable-event --userspace --channel=my-channel app:tp +$ lttng enable-event --userspace --channel=other-channel app:tp ---- If both channels are enabled, when a tracepoint named `app:tp` is @@ -6305,7 +5954,7 @@ previously, use the man:lttng-disable-channel(1) command. ==== [role="term"] ---- -lttng disable-channel --kernel my-channel +$ lttng disable-channel --kernel my-channel ---- ==== @@ -6353,7 +6002,7 @@ of the current tracing session. [role="term"] ---- -lttng add-context --userspace --type=vpid --type=perf:thread:cpu-cycles +$ lttng add-context --userspace --type=vpid --type=perf:thread:cpu-cycles ---- ==== @@ -6365,7 +6014,7 @@ tracing session. [role="term"] ---- -lttng add-context --kernel --channel=my-channel --type=tid +$ lttng add-context --kernel --channel=my-channel --type=tid ---- ==== @@ -6378,7 +6027,7 @@ in the channel named `my-channel`: [role="term"] ---- -lttng add-context --kernel --channel=my-channel \ +$ lttng add-context --kernel --channel=my-channel \ --type='$app:retriever:cur_msg_id' ---- @@ -6427,7 +6076,7 @@ tracks the specific PIDs. After: [role="term"] ---- -lttng track --pid=3,4,7,10,13 +$ lttng track --pid=3,4,7,10,13 ---- the whitelist is: @@ -6440,7 +6089,7 @@ You can add more PIDs to the whitelist afterwards: [role="term"] ---- -lttng track --pid=1,15,16 +$ lttng track --pid=1,15,16 ---- The result is: @@ -6454,7 +6103,7 @@ whitelist. Given the previous example, the following command: [role="term"] ---- -lttng untrack --pid=3,7,10,13 +$ lttng untrack --pid=3,7,10,13 ---- leads to this whitelist: @@ -6463,12 +6112,12 @@ leads to this whitelist: .PIDs 3, 7, 10, and 13 are removed from the whitelist. image::track-1-4-15-16.png[] -LTTng can track all possible PIDs again using the opt:track(1):--all -option: +LTTng can track all possible PIDs again using the +opt:lttng-track(1):--all option: [role="term"] ---- -lttng track --pid --all +$ lttng track --pid --all ---- The result is, again: @@ -6489,7 +6138,7 @@ man:lttng-untrack(1) command to clear the whitelist after you [role="term"] ---- -lttng untrack --pid --all +$ lttng untrack --pid --all ---- gives: @@ -6505,7 +6154,7 @@ specific PIDs, for example: [role="term"] ---- -lttng track --pid=6,11 +$ lttng track --pid=6,11 ---- Result: @@ -6543,7 +6192,7 @@ To save a given tracing session configuration: -- [role="term"] ---- -lttng save my-session +$ lttng save my-session ---- -- + @@ -6570,7 +6219,7 @@ To load a tracing session: -- [role="term"] ---- -lttng load my-session +$ lttng load my-session ---- -- + @@ -6598,7 +6247,7 @@ To send the trace data over the network: -- [role="term"] ---- -lttng-relayd +$ lttng-relayd ---- -- @@ -6608,7 +6257,7 @@ lttng-relayd -- [role="term"] ---- -lttng create my-session --set-url=net://remote-system +$ lttng create my-session --set-url=net://remote-system ---- -- + @@ -6617,7 +6266,7 @@ 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 intead of flushing + 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. @@ -6654,7 +6303,7 @@ To use LTTng live: -- [role="term"] ---- -lttng create my-session --live +$ lttng create my-session --live ---- -- + @@ -6666,7 +6315,8 @@ This spawns a local relay daemon. -- [role="term"] ---- -babeltrace --input-format=lttng-live net://localhost/host/hostname/my-session +$ babeltrace --input-format=lttng-live + net://localhost/host/hostname/my-session ---- -- + @@ -6684,7 +6334,7 @@ You can list the available live tracing sessions with Babeltrace: [role="term"] ---- -babeltrace --input-format=lttng-live net://localhost +$ babeltrace --input-format=lttng-live net://localhost ---- You can start the relay daemon on another system. In this case, you need @@ -6721,7 +6371,7 @@ To take a snapshot: -- [role="term"] ---- -lttng create --snapshot my-session +$ lttng create my-session --snapshot ---- -- + @@ -6744,7 +6394,7 @@ change before you actually take the snapshot. -- [role="term"] ---- -lttng snapshot record --name=my-first-snapshot +$ lttng snapshot record --name=my-first-snapshot ---- -- + @@ -6782,7 +6432,7 @@ XML machine interface output, for example: [role="term"] ---- -lttng --mi=xml enable-event --kernel --syscall open +$ lttng --mi=xml enable-event --kernel --syscall open ---- A schema definition (XSD) is @@ -6817,7 +6467,7 @@ To regenerate the metadata of an LTTng trace: -- [role="term"] ---- -lttng metadata regenerate +$ lttng metadata regenerate ---- -- @@ -6864,7 +6514,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 ---- -- @@ -6877,7 +6527,7 @@ lttng create --shm-path=/path/to/shm -- [role="term"] ---- -lttng-crash /path/to/shm +$ lttng-crash /path/to/shm ---- -- @@ -6892,7 +6542,7 @@ To convert the ring buffer files to LTTng trace files: -- [role="term"] ---- -lttng-crash --extract=/path/to/trace /path/to/shm +$ lttng-crash --extract=/path/to/trace /path/to/shm ---- -- @@ -7273,7 +6923,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. <>::