X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=f17290470b896c8df68742b9dbfe19805ce97baa;hb=ded026983bfe6b3ba0365bba59c93b4aa55bb37a;hp=b4580e6e17d10f915543c7e3a09bd872e56d017c;hpb=a8fb854044cc7313d16cc019dc1cbffdaeb9edea;p=lttng-docs.git diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt index b4580e6..f172904 100644 --- a/2.8/lttng-docs-2.8.txt +++ b/2.8/lttng-docs-2.8.txt @@ -1,7 +1,7 @@ The LTTng Documentation ======================= Philippe Proulx -v2.8, 28 November 2016 +v2.8, 20 February 2017 include::../common/copyright.txt[] @@ -74,6 +74,15 @@ include::../common/acknowledgements.txt[] [[whats-new]] == What's new in LTTng {revision}? +LTTng{nbsp}{revision} bears the name _Isseki Nicho_. The result of a +collaboration between http://www.dieuduciel.com/[Dieu du Ciel!] and +Nagano-based Shiga Kogen, +https://www.beeradvocate.com/beer/profile/1141/53111/[_**Isseki +Nicho**_] is a strong Imperial Dark Saison offering a rich roasted malt +flavor combined with a complex fruity finish typical of Saison yeasts. + +New features and changes in LTTng{nbsp}{revision}: + * **Tracing control**: ** You can attach <> to a <> with the @@ -82,7 +91,7 @@ include::../common/acknowledgements.txt[] -- [role="term"] ---- -lttng add-context --jul --type='$app.retriever:cur_msg_id' +$ lttng add-context --jul --type='$app.retriever:cur_msg_id' ---- -- + @@ -101,7 +110,7 @@ are supported. -- [role="term"] ---- -lttng enable-event --log4j my_logger \ +$ lttng enable-event --log4j my_logger \ --filter='$app.retriever:cur_msg_id == 23' ---- -- @@ -195,7 +204,7 @@ for an overview of the small API. -- [role="term"] ---- -man lttng-enable-event +$ man lttng-enable-event ---- -- + @@ -372,11 +381,11 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 28 November 2016. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 2 December 2016. |==== |Distribution |Available in releases |Alternatives -|Ubuntu +|https://www.ubuntu.com/[Ubuntu] |<>. |LTTng{nbsp}{revision} for Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_: @@ -389,43 +398,42 @@ link:/docs/v2.9#doc-ubuntu-ppa[use the LTTng Stable{nbsp}2.9 PPA]. <> for other Ubuntu releases. -|Fedora +|https://getfedora.org/[Fedora] |<>. |<> for other Fedora releases. -|Debian +|https://www.debian.org/[Debian] |<>. |<> for previous Debian releases. -|openSUSE +|https://www.opensuse.org/[openSUSE] |_Not available_ |<>. -|Arch Linux +|https://www.archlinux.org/[Arch Linux] |_Not available_ |link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR]. -|Alpine Linux +|https://alpinelinux.org/[Alpine Linux] |<>. |LTTng{nbsp}{revision} for Alpine Linux{nbsp}3.5 (not released yet). <> for other Alpine Linux releases. -|RHEL and SLES +|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] |See http://packages.efficios.com/[EfficiOS Enterprise Packages]. | -|Buildroot -|_Not available_ -|LTTng{nbsp}{revision} for Buildroot{nbsp}2016.11 (not released yet). - -<> for +|https://buildroot.org/[Buildroot] +|<>. +|<> for other Buildroot releases. -|OpenEmbedded and Yocto +|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and +https://www.yoctoproject.org/[Yocto] |<> (`openembedded-core` layer). |<> for other OpenEmbedded releases. @@ -446,9 +454,9 @@ To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.10 _Yakkety Yak_: -- [role="term"] ---- -sudo apt-get install lttng-tools -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev +# apt-get install lttng-tools +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev ---- -- @@ -459,7 +467,7 @@ sudo apt-get install liblttng-ust-dev -- [role="term"] ---- -sudo apt-get install liblttng-ust-agent-java +# apt-get install liblttng-ust-agent-java ---- -- @@ -470,7 +478,7 @@ sudo apt-get install liblttng-ust-agent-java -- [role="term"] ---- -sudo apt-get install python3-lttngust +# apt-get install python3-lttngust ---- -- @@ -493,8 +501,8 @@ To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: -- [role="term"] ---- -sudo apt-add-repository ppa:lttng/stable-2.8 -sudo apt-get update +# apt-add-repository ppa:lttng/stable-2.8 +# apt-get update ---- -- @@ -503,9 +511,9 @@ sudo apt-get update -- [role="term"] ---- -sudo apt-get install lttng-tools -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev +# apt-get install lttng-tools +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev ---- -- @@ -516,7 +524,7 @@ sudo apt-get install liblttng-ust-dev -- [role="term"] ---- -sudo apt-get install liblttng-ust-agent-java +# apt-get install liblttng-ust-agent-java ---- -- @@ -527,7 +535,7 @@ sudo apt-get install liblttng-ust-agent-java -- [role="term"] ---- -sudo apt-get install python3-lttngust +# apt-get install python3-lttngust ---- -- @@ -543,8 +551,8 @@ To install LTTng{nbsp}{revision} on Fedora{nbsp}25: -- [role="term"] ---- -sudo yum install lttng-tools -sudo yum install lttng-ust +# yum install lttng-tools +# yum install lttng-ust ---- -- @@ -553,7 +561,7 @@ sudo yum install lttng-ust -- [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.* && @@ -590,9 +598,9 @@ To install LTTng{nbsp}{revision} on Debian "stretch" (testing): -- [role="term"] ---- -sudo apt-get install lttng-modules-dkms -sudo apt-get install liblttng-ust-dev -sudo apt-get install lttng-tools +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev +# apt-get install lttng-tools ---- -- @@ -602,7 +610,7 @@ sudo apt-get install lttng-tools -- [role="term"] ---- -sudo apt-get install liblttng-ust-agent-java +# apt-get install liblttng-ust-agent-java ---- -- @@ -612,7 +620,7 @@ sudo apt-get install liblttng-ust-agent-java -- [role="term"] ---- -sudo apt-get install python3-lttngust +# apt-get install python3-lttngust ---- -- @@ -632,8 +640,8 @@ Alpine Linux "edge": -- [role="term"] ---- -sudo apk add lttng-tools -sudo apk add lttng-ust-dev +# apk add lttng-tools +# apk add lttng-ust-dev ---- -- @@ -645,7 +653,7 @@ on Alpine Linux "edge": -- [role="term"] ---- -apk add linux-vanilla linux-vanilla-dev +# apk add linux-vanilla linux-vanilla-dev ---- -- @@ -655,7 +663,7 @@ apk add linux-vanilla linux-vanilla-dev -- [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.* && @@ -666,6 +674,36 @@ 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 @@ -708,14 +746,6 @@ LTTng-UST{nbsp}{revision} from source and pass the ==== -[[enterprise-distributions]] -=== RHEL, SUSE, and other enterprise distributions - -To install LTTng on enterprise Linux distributions, such as Red Hat -Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SUSE), please -see http://packages.efficios.com/[EfficiOS Enterprise Packages]. - - [[building-from-source]] === Build from source @@ -736,7 +766,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.* && @@ -751,7 +781,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.* && @@ -801,7 +831,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.* && @@ -839,16 +869,18 @@ 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 <>: +. Create a <> which writes its traces + to dir:{/tmp/my-kernel-trace}: + -- [role="term"] ---- -sudo lttng create my-kernel-session +# lttng create my-kernel-session --output=/tmp/my-kernel-trace ---- -- @@ -857,42 +889,46 @@ sudo lttng create my-kernel-session -- [role="term"] ---- -lttng list --kernel +# lttng list --kernel +# lttng list --kernel --syscall ---- -- -. Create an <> which matches the desired event names, - for example `sched_switch` and `sched_process_fork`: +. Create <> which match the desired instrumentation + point names, for example the `sched_switch` and `sched_process_fork` + tracepoints, and the man:open(2) and man:close(2) system calls: + -- [role="term"] ---- -sudo lttng enable-event --kernel sched_switch,sched_process_fork +# lttng enable-event --kernel sched_switch,sched_process_fork +# lttng enable-event --kernel --syscall open,close ---- -- + -You can also create an event rule which _matches_ all the Linux kernel +You can also create an event rule which matches _all_ the Linux kernel tracepoints (this will generate a lot of data when tracing): + -- [role="term"] ---- -sudo lttng enable-event --kernel --all +# lttng enable-event --kernel --all ---- -- -. Start tracing: +. <>: + -- [role="term"] ---- -sudo lttng start +# lttng start ---- -- . Do some operation on your system for a few seconds. For example, load a website, or list the files of a directory. -. Stop tracing and destroy the tracing session: +. <> and destroy the + tracing session: + -- [role="term"] @@ -905,10 +941,15 @@ sudo lttng destroy The man:lttng-destroy(1) command does not destroy the trace data; it only destroys the state of the tracing session. -By default, LTTng saves the traces in -+$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+, -where +__name__+ is the tracing session name. Note that the -env:LTTNG_HOME environment variable defaults to `$HOME` if not set. +. For the sake of this example, make the recorded trace accessible to + the non-root users: ++ +-- +[role="term"] +---- +sudo chown -R $(whoami) /tmp/my-kernel-trace +---- +-- See <> to view the recorded events. @@ -977,7 +1018,7 @@ TRACEPOINT_EVENT( -- [role="term"] ---- -gcc -c -I. hello-tp.c +$ gcc -c -I. hello-tp.c ---- -- @@ -1037,7 +1078,7 @@ int main(int argc, char *argv[]) -- [role="term"] ---- -gcc -c hello.c +$ gcc -c hello.c ---- -- @@ -1047,7 +1088,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 ---- -- @@ -1064,7 +1105,7 @@ To trace the user application: -- [role="term"] ---- -./hello world and beyond +$ ./hello world and beyond ---- -- + @@ -1082,7 +1123,7 @@ Press Enter to continue... -- [role="term"] ---- -lttng-sessiond --daemonize +$ lttng-sessiond --daemonize ---- -- + @@ -1094,7 +1135,7 @@ a service that the distribution's service manager started. -- [role="term"] ---- -lttng list --userspace +$ lttng list --userspace ---- -- + @@ -1106,7 +1147,7 @@ under the `./hello` process. -- [role="term"] ---- -lttng create my-user-space-session +$ lttng create my-user-space-session ---- -- @@ -1116,28 +1157,29 @@ 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 ---- -- -. Start tracing: +. <>: + -- [role="term"] ---- -lttng start +$ lttng start ---- -- . Go back to the running `hello` application and press Enter. The program executes all `tracepoint()` instrumentation points and exits. -. Stop tracing and destroy the tracing session: +. <> and destroy the + tracing session: + -- [role="term"] ---- -sudo lttng stop -sudo lttng destroy +$ lttng stop +$ lttng destroy ---- -- + @@ -1146,7 +1188,7 @@ only destroys the state of the tracing session. By default, LTTng saves the traces in +$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+, -where +__name__+ is the tracing session name. Note that the +where +__name__+ is the tracing session name. The env:LTTNG_HOME environment variable defaults to `$HOME` if not set. See < +$ lttng ---- The <> section explores the @@ -2918,7 +2960,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -2927,7 +2969,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 ---- -- @@ -2938,7 +2980,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -2956,7 +2998,7 @@ To create the tracepoint provider package archive file: -- [role="term"] ---- -gcc -I. -c tpp.c +$ gcc -I. -c tpp.c ---- -- @@ -2965,7 +3007,7 @@ gcc -I. -c tpp.c -- [role="term"] ---- -ar rcs tpp.a tpp.o +$ ar rcs tpp.a tpp.o ---- -- @@ -2985,7 +3027,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -2994,7 +3036,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 ---- -- @@ -3005,7 +3047,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3034,7 +3076,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3043,7 +3085,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -ltpp +$ gcc -o app app.o -ldl -L. -ltpp ---- -- @@ -3054,7 +3096,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3085,7 +3127,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3094,7 +3136,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl +$ gcc -o app app.o -ldl ---- -- @@ -3106,7 +3148,7 @@ To run the instrumented application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3117,7 +3159,7 @@ To run the instrumented application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3150,7 +3192,7 @@ To build the instrumented application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3159,7 +3201,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl +$ gcc -o app app.o -ldl ---- -- @@ -3170,7 +3212,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3202,7 +3244,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3211,7 +3253,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 ---- -- @@ -3222,7 +3264,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3231,7 +3273,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3242,7 +3284,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3274,7 +3316,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3283,7 +3325,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 ---- -- @@ -3294,7 +3336,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3303,7 +3345,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3314,7 +3356,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3332,7 +3374,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3347,7 +3389,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3356,7 +3398,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 ---- -- @@ -3367,7 +3409,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3376,7 +3418,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3388,7 +3430,7 @@ To run the application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3399,7 +3441,7 @@ To run the application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3419,7 +3461,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3434,7 +3476,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3443,7 +3485,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 ---- -- @@ -3454,7 +3496,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3463,7 +3505,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3474,7 +3516,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3508,7 +3550,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3517,7 +3559,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 ---- -- @@ -3528,7 +3570,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3537,7 +3579,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -lemon +$ gcc -o app app.o -ldl -L. -lemon ---- -- @@ -3548,7 +3590,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3568,7 +3610,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3583,7 +3625,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3592,7 +3634,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 ---- -- @@ -3603,7 +3645,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3612,7 +3654,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -ldl -L. -lemon +$ gcc -o app app.o -ldl -L. -lemon ---- -- @@ -3623,7 +3665,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3641,7 +3683,7 @@ include::../common/ust-sit-step-tp-so.txt[] To build the instrumented user library: . In path:{emon.c}, before including path:{tpp.h}, add the - following line: + following lines: + -- [source,c] @@ -3656,7 +3698,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3665,7 +3707,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 ---- -- @@ -3676,7 +3718,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3685,7 +3727,7 @@ gcc -c app.c -- [role="term"] ---- -gcc -o app app.o -L. -lemon +$ gcc -o app app.o -L. -lemon ---- -- @@ -3697,7 +3739,7 @@ To run the application with tracing support: -- [role="term"] ---- -LD_PRELOAD=./libtpp.so ./app +$ LD_PRELOAD=./libtpp.so ./app ---- -- @@ -3708,7 +3750,7 @@ To run the application without tracing support: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3740,7 +3782,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3749,7 +3791,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o +$ gcc -shared -o libemon.so emon.o ---- -- @@ -3760,7 +3802,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3769,7 +3811,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 ---- -- @@ -3780,7 +3822,7 @@ To run the instrumented application: -- [role="term"] ---- -./app +$ ./app ---- -- @@ -3811,7 +3853,7 @@ To build the application: -- [role="term"] ---- -gcc -c app.c +$ gcc -c app.c ---- -- @@ -3820,7 +3862,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 ---- -- @@ -3836,7 +3878,7 @@ To build the instrumented user library: -- [role="term"] ---- -gcc -I. -fpic -c emon.c +$ gcc -I. -fpic -c emon.c ---- -- @@ -3845,7 +3887,7 @@ gcc -I. -fpic -c emon.c -- [role="term"] ---- -gcc -shared -o libemon.so emon.o +$ gcc -shared -o libemon.so emon.o ---- -- @@ -3856,7 +3898,7 @@ To run the application: -- [role="term"] ---- -./app +$ ./app ---- -- |==== @@ -3895,7 +3937,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 @@ -3904,7 +3946,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 ---- @@ -3918,7 +3960,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) ---- @@ -3943,7 +3985,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.* && @@ -3970,7 +4012,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.* && @@ -3995,7 +4037,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' ---- ==== @@ -4005,12 +4047,14 @@ 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.* && ./configure --libdir=/usr/local/lib32 CFLAGS=-m32 CXXFLAGS=-m32 \ - LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' && + LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' \ + --disable-bin-lttng --disable-bin-lttng-crash \ + --disable-bin-lttng-relayd --disable-bin-lttng-sessiond && make && cd src/bin/lttng-consumerd && sudo make install && @@ -4027,7 +4071,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.* && @@ -4054,9 +4098,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 @@ -4108,7 +4152,7 @@ To use `tracef()` in your application: -- [role="term"] ---- -gcc -o app app.c -llttng-ust +$ gcc -o app app.c -llttng-ust ---- -- @@ -4120,7 +4164,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:*' ---- -- @@ -4195,7 +4239,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 ---- -- @@ -4209,7 +4253,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 ---- -- @@ -4223,7 +4267,7 @@ _specific log level_: -- [role="term"] ---- -lttng enable-event --userspace 'lttng_ust_tracelog:*' +$ lttng enable-event --userspace 'lttng_ust_tracelog:*' --loglevel-only=TRACE_INFO ---- -- @@ -4262,7 +4306,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 ---- -- + @@ -4271,7 +4315,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 ---- -- @@ -4321,7 +4365,7 @@ The path:{liblttng-ust-cyg-profile*.so} helpers can add instrumentation to the entry and exit points of functions. man:gcc(1) and man:clang(1) have an option named -https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html[`-finstrument-functions`] +https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html[`-finstrument-functions`] which generates instrumentation calls for entry and exit to functions. The LTTng-UST function tracing helpers, path:{liblttng-ust-cyg-profile.so} and @@ -4514,7 +4558,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 ---- <>, @@ -4523,16 +4567,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 @@ -4540,11 +4584,36 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== +In the resulting trace, an <> generated by a Java +application using `java.util.logging` is named `lttng_jul:event` and +has the following fields: + +`msg`:: + Log record's message. + +`logger_name`:: + Logger name. + +`class_name`:: + Name of the class in which the log statement was executed. + +`method_name`:: + Name of the method in which the log statement was executed. + +`long_millis`:: + Logging time (timestamp in milliseconds). + +`int_loglevel`:: + Log level integer value. + +`int_threadid`:: + ID of the thread in which the log statement was executed. + You can use the opt:lttng-enable-event(1):--loglevel or opt:lttng-enable-event(1):--loglevel-only option of the man:lttng-enable-event(1) command to target a range of JUL log levels @@ -4662,7 +4731,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 ---- <>, @@ -4671,16 +4740,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 @@ -4688,11 +4757,42 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== +In the resulting trace, an <> generated by a Java +application using log4j is named `lttng_log4j:event` and +has the following fields: + +`msg`:: + Log record's message. + +`logger_name`:: + Logger name. + +`class_name`:: + Name of the class in which the log statement was executed. + +`method_name`:: + Name of the method in which the log statement was executed. + +`filename`:: + Name of the file in which the executed log statement is located. + +`line_number`:: + Line number at which the log statement was executed. + +`timestamp`:: + Logging timestamp. + +`int_loglevel`:: + Log level integer value. + +`thread_name`:: + Name of the Java thread in which the log statement was executed. + You can use the opt:lttng-enable-event(1):--loglevel or opt:lttng-enable-event(1):--loglevel-only option of the man:lttng-enable-event(1) command to target a range of Apache log4j log levels @@ -4862,7 +4962,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 ---- <> @@ -4871,8 +4971,8 @@ and <> matching the [role="term"] ---- -lttng create -lttng enable-event --jul jello +$ lttng create +$ lttng enable-event --jul jello ---- <> to the @@ -4880,22 +4980,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 @@ -4903,8 +5003,8 @@ recorded events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -4990,16 +5090,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 @@ -5007,11 +5107,38 @@ events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== +In the resulting trace, an <> generated by a Python +application is named `lttng_python:event` and has the following fields: + +`asctime`:: + Logging time (string). + +`msg`:: + Log record's message. + +`logger_name`:: + Logger name. + +`funcName`:: + Name of the function in which the log statement was executed. + +`lineno`:: + Line number at which the log statement was executed. + +`int_loglevel`:: + Log level integer value. + +`thread`:: + ID of the Python thread in which the log statement was executed. + +`threadName`:: + Name of the Python thread in which the log statement was executed. + You can use the opt:lttng-enable-event(1):--loglevel or opt:lttng-enable-event(1):--loglevel-only option of the man:lttng-enable-event(1) command to target a range of Python log levels @@ -5052,15 +5179,15 @@ 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 belongs to the Linux kernel <>. However, unlike other instrumentation points in the kernel tracing domain, **any Unix user** can <> which -matches its event name, not only the root user or users in the tracing -group. +matches its event name, not only the root user or users in the +<>. To use the LTTng logger: @@ -5098,16 +5225,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 @@ -5115,8 +5242,8 @@ events: [role="term"] ---- -lttng stop -lttng view +$ lttng stop +$ lttng view ---- ==== @@ -5187,7 +5314,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.* @@ -5302,8 +5429,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 ---- -- + @@ -5420,7 +5547,7 @@ module: ==== [role="term"] ---- -sudo lttng-sessiond --extra-kmod-probes=my_subsys,usb +# lttng-sessiond --extra-kmod-probes=my_subsys,usb ---- ==== -- @@ -5438,7 +5565,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 ---- ==== -- @@ -5450,7 +5577,7 @@ To confirm that a probe module is loaded: -- [role="term"] ---- -lsmod | grep lttng_probe_usb +$ lsmod | grep lttng_probe_usb ---- -- @@ -5461,7 +5588,7 @@ To unload the loaded probe modules: -- [role="term"] ---- -sudo pkill lttng-sessiond +# pkill lttng-sessiond ---- -- + @@ -5523,7 +5650,7 @@ To start a user session daemon: -- [role="term"] ---- -lttng-sessiond --daemonize +$ lttng-sessiond --daemonize ---- -- @@ -5534,7 +5661,7 @@ To start the root session daemon: -- [role="term"] ---- -sudo lttng-sessiond --daemonize +# lttng-sessiond --daemonize ---- -- @@ -5563,7 +5690,7 @@ To create a tracing session with a generated name: -- [role="term"] ---- -lttng create +$ lttng create ---- -- @@ -5577,7 +5704,7 @@ To create a tracing session with a specific name: -- [role="term"] ---- -lttng create my-session +$ lttng create my-session ---- -- + @@ -5597,7 +5724,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 ---- -- @@ -5610,7 +5737,7 @@ To list all the existing tracing sessions for your Unix user: -- [role="term"] ---- -lttng list +$ lttng list ---- -- @@ -5641,7 +5768,7 @@ To change the current tracing session: -- [role="term"] ---- -lttng set-session new-session +$ lttng set-session new-session ---- -- + @@ -5659,7 +5786,7 @@ To destroy the current tracing session: -- [role="term"] ---- -lttng destroy +$ lttng destroy ---- -- @@ -5696,7 +5823,7 @@ To list the available instrumentation points: ==== [role="term"] ---- -lttng list --userspace +$ lttng list --userspace ---- ==== @@ -5704,7 +5831,7 @@ lttng list --userspace ==== [role="term"] ---- -lttng list --kernel --syscall +$ lttng list --kernel --syscall ---- ==== @@ -5808,7 +5935,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 ---- ==== @@ -5816,7 +5943,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 ---- ==== @@ -5824,18 +5951,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' ---- @@ -5847,7 +5974,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 @@ -5858,7 +5985,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' ---- ==== @@ -5867,7 +5994,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 ---- ==== @@ -5875,7 +6002,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 ---- ==== @@ -5887,8 +6014,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 ---- @@ -5912,7 +6039,7 @@ a _disabled_ event rule. ==== [role="term"] ---- -lttng disable-event --python my-logger +$ lttng disable-event --python my-logger ---- ==== @@ -5920,7 +6047,7 @@ lttng disable-event --python my-logger ==== [role="term"] ---- -lttng disable-event --jul '*' +$ lttng disable-event --jul '*' ---- ==== @@ -5933,7 +6060,7 @@ rules of a given channel. [role="term"] ---- -lttng disable-event --jul --all-events +$ lttng disable-event --jul --all-events ---- ==== @@ -5951,7 +6078,7 @@ parameters, its channels, event rules, and their attributes: -- [role="term"] ---- -lttng status +$ lttng status ---- -- + @@ -5963,7 +6090,7 @@ To get the status of any tracing session: -- [role="term"] ---- -lttng list my-session +$ lttng list my-session ---- -- + @@ -5985,7 +6112,7 @@ To start tracing in the current tracing session: -- [role="term"] ---- -lttng start +$ lttng start ---- -- @@ -6001,7 +6128,7 @@ To stop tracing in the current tracing session: -- [role="term"] ---- -lttng stop +$ lttng stop ---- -- + @@ -6126,7 +6253,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 ---- ==== @@ -6134,7 +6261,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 ---- ==== @@ -6143,7 +6270,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 ---- ==== @@ -6152,7 +6279,7 @@ lttng enable-channel --kernel --tracefile-count=8 \ ==== [role="term"] ---- -lttng enable-channel --userspace --overwrite my-channel +$ lttng enable-channel --userspace --overwrite my-channel ---- ==== @@ -6161,8 +6288,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 @@ -6179,7 +6306,7 @@ previously, use the man:lttng-disable-channel(1) command. ==== [role="term"] ---- -lttng disable-channel --kernel my-channel +$ lttng disable-channel --kernel my-channel ---- ==== @@ -6227,7 +6354,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 ---- ==== @@ -6239,7 +6366,7 @@ tracing session. [role="term"] ---- -lttng add-context --kernel --channel=my-channel --type=tid +$ lttng add-context --kernel --channel=my-channel --type=tid ---- ==== @@ -6252,7 +6379,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' ---- @@ -6301,7 +6428,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: @@ -6314,7 +6441,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: @@ -6328,7 +6455,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: @@ -6342,7 +6469,7 @@ option: [role="term"] ---- -lttng track --pid --all +$ lttng track --pid --all ---- The result is, again: @@ -6363,7 +6490,7 @@ man:lttng-untrack(1) command to clear the whitelist after you [role="term"] ---- -lttng untrack --pid --all +$ lttng untrack --pid --all ---- gives: @@ -6379,7 +6506,7 @@ specific PIDs, for example: [role="term"] ---- -lttng track --pid=6,11 +$ lttng track --pid=6,11 ---- Result: @@ -6417,7 +6544,7 @@ To save a given tracing session configuration: -- [role="term"] ---- -lttng save my-session +$ lttng save my-session ---- -- + @@ -6444,7 +6571,7 @@ To load a tracing session: -- [role="term"] ---- -lttng load my-session +$ lttng load my-session ---- -- + @@ -6472,7 +6599,7 @@ To send the trace data over the network: -- [role="term"] ---- -lttng-relayd +$ lttng-relayd ---- -- @@ -6482,7 +6609,7 @@ lttng-relayd -- [role="term"] ---- -lttng create my-session --set-url=net://remote-system +$ lttng create my-session --set-url=net://remote-system ---- -- + @@ -6491,7 +6618,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. @@ -6528,7 +6655,7 @@ To use LTTng live: -- [role="term"] ---- -lttng create --live my-session +$ lttng create my-session --live ---- -- + @@ -6540,7 +6667,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 ---- -- + @@ -6558,7 +6686,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 @@ -6595,7 +6723,7 @@ To take a snapshot: -- [role="term"] ---- -lttng create --snapshot my-session +$ lttng create my-session --snapshot ---- -- + @@ -6618,7 +6746,7 @@ change before you actually take the snapshot. -- [role="term"] ---- -lttng snapshot record --name=my-first-snapshot +$ lttng snapshot record --name=my-first-snapshot ---- -- + @@ -6656,7 +6784,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 @@ -6691,7 +6819,7 @@ To regenerate the metadata of an LTTng trace: -- [role="term"] ---- -lttng metadata regenerate +$ lttng metadata regenerate ---- -- @@ -6738,7 +6866,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 ---- -- @@ -6751,7 +6879,7 @@ lttng create --shm-path=/path/to/shm -- [role="term"] ---- -lttng-crash /path/to/shm +$ lttng-crash /path/to/shm ---- -- @@ -6766,7 +6894,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 ---- -- @@ -7318,7 +7446,7 @@ tracer:: <>:: A namespace for event sources. -tracing group:: +<>:: The Unix group in which a Unix user can be to be allowed to trace the Linux kernel.