X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=e38cafe2c6aa5d4534058788303269b4c659ec8b;hb=664335c3473a73a5164ed35e107163999a7ac933;hp=e0ae8088f8e2bbe396209a537610f501c5dd0e3a;hpb=f4a596c4aa04fc54139f00f1b77a676a7f4c3779;p=lttng-docs.git diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt index e0ae808..e38cafe 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, 25 October 2016 +v2.8, 8 December 2016 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 @@ -372,70 +381,60 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions. +.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_: <>. +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. -|Fedora -|_Not available_ -|LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} for -Fedora{nbsp}25 and Fedora{nbsp}26 (both are not released yet). - -<>. - -<> for +|https://getfedora.org/[Fedora] +|<>. +|<> for other Fedora releases. -|Debian -|<> -| -<> for +|https://www.debian.org/[Debian] +|<>. +|<> for previous Debian releases. -|openSUSE +|https://www.opensuse.org/[openSUSE] |_Not available_ -|LTTng{nbsp}2.7 for openSUSE Leap{nbsp}42.1. +|<>. -<> for -other openSUSE releases. - -|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). - -LTTng{nbsp}2.7 for Buildroot{nbsp}2016.02, Buildroot{nbsp}2016.05, -and Buildroot{nbsp}2016.08. - -<> for +|https://buildroot.org/[Buildroot] +|<>. +|<> for other Buildroot releases. -|OpenEmbedded and Yocto -|<> (`openembedded-core` layer) +|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and +https://www.yoctoproject.org/[Yocto] +|<> (`openembedded-core` layer). |<> for other OpenEmbedded releases. |==== @@ -473,7 +472,7 @@ sudo apt-get install liblttng-ust-agent-java -- . **If you need to instrument and trace - <>**, install the + <>**, install the LTTng-UST Python agent: + -- @@ -530,7 +529,7 @@ sudo apt-get install liblttng-ust-agent-java -- . **If you need to instrument and trace - <>**, install the + <>**, install the LTTng-UST Python agent: + -- @@ -541,57 +540,77 @@ sudo apt-get install python3-lttngust -- -[[debian]] -=== Debian +[[fedora]] +=== Fedora -To install LTTng{nbsp}{revision} on Debian "stretch" (testing): +To install LTTng{nbsp}{revision} on Fedora{nbsp}25: -. Install the main LTTng{nbsp}{revision} packages: +. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{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 +sudo yum install lttng-tools +sudo yum install lttng-ust ---- -- -. **If you need to instrument and trace <>**, install the LTTng-UST Java agent: +. Download, build, and install the latest LTTng-modules{nbsp}{revision}: + -- [role="term"] ---- -sudo apt-get install liblttng-ust-agent-java +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 ---- -- -. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: +[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 python3-lttngust +sudo apt-get install lttng-modules-dkms +sudo apt-get install liblttng-ust-dev +sudo apt-get install lttng-tools ---- -- - -[[arch-linux]] -=== Arch Linux - -To install LTTng{nbsp}{revision} on Arch Linux using -https://archlinux.fr/yaourt-en[Yaourt]: - -. Install the main LTTng{nbsp}{revision} packages: +. **If you need to instrument and trace <>**, install the LTTng-UST Java agent: + -- [role="term"] ---- -yaourt -S lttng-tools -yaourt -S lttng-ust -yaourt -S lttng-modules +sudo apt-get install liblttng-ust-agent-java ---- -- @@ -601,8 +620,7 @@ yaourt -S lttng-modules -- [role="term"] ---- -yaourt -S python-lttngust -yaourt -S python2-lttngust +sudo apt-get install python3-lttngust ---- -- @@ -610,8 +628,8 @@ yaourt -S python2-lttngust [[alpine-linux]] === Alpine Linux -To install LTTng{nbsp}{revision} (tracing control and user space -tracing) on Alpine Linux "edge": +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"]. @@ -656,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 @@ -698,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 @@ -831,14 +871,15 @@ This tutorial walks you through the steps to: 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 <>. +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 +sudo lttng create my-kernel-session --output=/tmp/my-kernel-trace ---- -- @@ -848,20 +889,23 @@ sudo lttng create my-kernel-session [role="term"] ---- 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 +sudo 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): + -- @@ -871,7 +915,7 @@ sudo lttng enable-event --kernel --all ---- -- -. Start tracing: +. <>: + -- [role="term"] @@ -882,7 +926,8 @@ sudo 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"] @@ -895,10 +940,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. @@ -1110,7 +1160,7 @@ lttng enable-event --userspace hello_world:my_first_tracepoint ---- -- -. Start tracing: +. <>: + -- [role="term"] @@ -1121,7 +1171,8 @@ 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"] @@ -1136,7 +1187,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 <> 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 @@ -4683,6 +4761,37 @@ 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 @@ -5002,6 +5111,33 @@ 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 @@ -5049,8 +5185,8 @@ 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: @@ -5587,7 +5723,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 ---- -- @@ -6518,7 +6654,7 @@ To use LTTng live: -- [role="term"] ---- -lttng create --live my-session +lttng create my-session --live ---- -- + @@ -6585,7 +6721,7 @@ To take a snapshot: -- [role="term"] ---- -lttng create --snapshot my-session +lttng create my-session --snapshot ---- -- + @@ -6728,7 +6864,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 ---- -- @@ -7308,7 +7444,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.