X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=2.10%2Flttng-docs-2.10.txt;h=d237bcace6b83e07809c7b9556a64f545f98d284;hb=9fe3b57a66d50c9ac5923a666fcb8451f0d0cdea;hp=6c549393dc120bc1bf3eafe7595244416ee07b8c;hpb=90c4e38a967f3ad7f22c404eab9b6e6b0c7d6df0;p=lttng-docs.git diff --git a/2.10/lttng-docs-2.10.txt b/2.10/lttng-docs-2.10.txt index 6c54939..d237bca 100644 --- a/2.10/lttng-docs-2.10.txt +++ b/2.10/lttng-docs-2.10.txt @@ -1,12 +1,15 @@ The LTTng Documentation ======================= Philippe Proulx -v2.10, 31 July 2017 +v2.10, 18 October 2019 include::../common/copyright.txt[] +include::../common/warning-not-maintained.txt[] + + include::../common/welcome.txt[] @@ -138,7 +141,7 @@ instrumented with LTTng-UST which is explicitly allowed to block: [role="term"] ---- $ lttng create -$ lttng enable-channel --userspace --blocking-timeout=-1 blocking-channel +$ lttng enable-channel --userspace --blocking-timeout=inf blocking-channel $ lttng enable-event --userspace --channel=blocking-channel --all $ lttng start $ LTTNG_UST_ALLOW_BLOCKING=1 my-app @@ -321,74 +324,104 @@ but note that: applications. [role="growable"] -.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 25 July 2017. +.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 18 October 2019. |==== -|Distribution |Available in releases |Alternatives +|Distribution |Available in releases |https://www.ubuntu.com/[Ubuntu] -|Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_: -<>. -|link:/docs/v2.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_]. +|xref:ubuntu[Ubuntu{nbsp}18.04 _Bionic Beaver_, +Ubuntu{nbsp}19.04 _Disco Dingo_, and +Ubuntu{nbsp}19.10 _Eoan Ermine_]. -<> for -other Ubuntu releases. +Ubuntu{nbsp}16.04 _Xenial Xerus_: +<>. |https://getfedora.org/[Fedora] -|_Not available_ -|link:/docs/v2.9#doc-fedora[LTTng{nbsp}2.9 for Fedora 26]. - -<>. +|xref:fedora[Fedora{nbsp}29, Fedora{nbsp}30, Fedora{nbsp}31, +and Fedora{nbsp}32]. |https://www.debian.org/[Debian] -|_Not available_ -|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" -(stable), Debian "buster" (testing), and Debian "sid" (unstable)]. - -<>. - -|https://www.archlinux.org/[Arch Linux] -|_Not available_ -|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 in the latest AUR packages]. +|<>. |https://alpinelinux.org/[Alpine Linux] -|_Not available_ -|link:/docs/v2.9#doc-alpine-linux[LTTng{nbsp}2.9 for Alpine Linux "edge"]. +|xref:alpine-linux[Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8, +Alpine Linux{nbsp}3.9, and Alpine Linux{nbsp}3.10]. -<>. +|https://www.opensuse.org/[openSUSE] +|<>. |https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES] |See http://packages.efficios.com/[EfficiOS Enterprise Packages]. -| |https://buildroot.org/[Buildroot] -|_Not available_ -|link:/docs/v2.9#doc-buildroot[LTTng{nbsp}2.9 for Buildroot{nbsp}2017.02 and -Buildroot{nbsp}2017.05]. - -<>. +|xref:buildroot[Buildroot{nbsp}2018.02, Buildroot{nbsp}2018.05, +Buildroot{nbsp}2018.08, Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.02, +Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08, and +Buildroot{nbsp}2018.11]. |http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and https://www.yoctoproject.org/[Yocto] -|_Not available_ -|link:/docs/v2.9#doc-oe-yocto[LTTng{nbsp}2.9 for Yocto Project{nbsp}2.3 _Pyro_] -(`openembedded-core` layer). - -<>. +|<>. |==== [[ubuntu]] === [[ubuntu-official-repositories]]Ubuntu +LTTng{nbsp}{revision} is available on: + +* Ubuntu{nbsp}18.04 _Bionic Beaver_ +* Ubuntu{nbsp}19.04 _Disco Dingo_ +* Ubuntu{nbsp}19.10 _Eoan Ermine_ + +For other releases of Ubuntu, <>. + +To install LTTng{nbsp}{revision} on Ubuntu{nbsp}18.04 _Bionic Beaver_, +Ubuntu{nbsp}19.04 _Disco Dingo_, or +Ubuntu{nbsp}19.10 _Eoan Ermine_: + +. Install the main LTTng{nbsp}{revision} packages: ++ +-- +[role="term"] +---- +# apt-get install lttng-tools +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev +---- +-- + +. **If you need to instrument and trace + <>**, install the LTTng-UST + Java agent: ++ +-- +[role="term"] +---- +# apt-get install liblttng-ust-agent-java +---- +-- + +. **If you need to instrument and trace + <>**, install the + LTTng-UST Python agent: ++ +-- +[role="term"] +---- +# apt-get install python3-lttngust +---- +-- + + [[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_ +LTTng{nbsp}{revision} packages for Ubuntu{nbsp}18.04 _Bionic Beaver_. To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: @@ -437,6 +470,159 @@ To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA: -- +[[fedora]] +=== Fedora + +To install LTTng{nbsp}{revision} on Fedora{nbsp}29, Fedora{nbsp}30, +Fedora{nbsp}31, or Fedora{nbsp}32: + +. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} + packages: ++ +-- +[role="term"] +---- +# yum install lttng-tools +# 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.10.tar.bz2 && +tar -xf lttng-modules-latest-2.10.tar.bz2 && +cd lttng-modules-2.10.* && +make && +sudo make modules_install && +sudo depmod -a +---- +-- + +[IMPORTANT] +.Java and Python application instrumentation and tracing +==== +If you need to instrument and trace <> on Fedora, 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 Fedora, 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 "buster" (stable) or +Debian "bullseye" (testing): + +. Install the main LTTng{nbsp}{revision} packages: ++ +-- +[role="term"] +---- +# apt-get install lttng-modules-dkms +# apt-get install liblttng-ust-dev +# apt-get install lttng-tools +---- +-- + +. **If you need to instrument and trace <>**, install the LTTng-UST Java agent: ++ +-- +[role="term"] +---- +# apt-get install liblttng-ust-agent-java +---- +-- + +. **If you need to instrument and trace <>**, install the LTTng-UST Python agent: ++ +-- +[role="term"] +---- +# apt-get install python3-lttngust +---- +-- + + +[[alpine-linux]] +=== Alpine Linux + +To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on +Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8, Alpine Linux{nbsp}3.9, or +Alpine Linux{nbsp}3.10: + +. Add the LTTng packages: ++ +-- +[role="term"] +---- +# apk add lttng-tools +# apk add lttng-ust-dev +---- +-- + +. Download, build, and install the latest LTTng-modules{nbsp}{revision}: ++ +-- +[role="term"] +---- +$ cd $(mktemp -d) && +wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.10.tar.bz2 && +tar -xf lttng-modules-latest-2.10.tar.bz2 && +cd lttng-modules-2.10.* && +make && +sudo make modules_install && +sudo depmod -a +---- +-- + + +[[opensuse]] +=== noch:{openSUSE} + +To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}15.1: + +* Install the main LTTng{nbsp}{revision} packages: ++ +-- +[role="term"] +---- +sudo zypper install lttng-tools +sudo zypper install lttng-modules +sudo zypper install lttng-ust-devel +---- +-- + +[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. +==== + + [[enterprise-distributions]] === RHEL, SUSE, and other enterprise distributions @@ -445,6 +631,75 @@ 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}2018.02, +Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08, +Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.02, +Buildroot{nbsp}2019.05, Buildroot{nbsp}2019.08, or +Buildroot{nbsp}2019.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.7 _Warrior_ and +Yocto Project{nbsp}3.0 _Zeus_ 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 Yocto/OpenEmbedded, 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 Yocto/OpenEmbedded, 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 @@ -626,19 +881,23 @@ tracepoints (this will generate a lot of data when tracing): . Do some operation on your system for a few seconds. For example, load a website, or list the files of a directory. -. <> and destroy the +. <> the current tracing session: + -- [role="term"] ---- -# lttng stop # lttng destroy ---- -- + The man:lttng-destroy(1) command does not destroy the trace data; it only destroys the state of the tracing session. ++ +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command +implicitly (see <>). You need to stop tracing to make LTTng flush the remaining +trace data and make the trace readable. . For the sake of this example, make the recorded trace accessible to the non-root users: @@ -871,19 +1130,23 @@ $ lttng start . Go back to the running `hello` application and press Enter. The program executes all `tracepoint()` instrumentation points and exits. -. <> and destroy the +. <> the current tracing session: + -- [role="term"] ---- -$ lttng stop $ lttng destroy ---- -- + The man:lttng-destroy(1) command does not destroy the trace data; it only destroys the state of the tracing session. ++ +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command +implicitly (see <>). You need to stop tracing to make LTTng flush the remaining +trace data and make the trace readable. By default, LTTng saves the traces in +$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+, @@ -1290,8 +1553,11 @@ reached, the channel's _event loss mode_ determines what to do. The available event loss modes are: Discard mode:: - Drop the newest event records until a the tracer - releases a sub-buffer. + Drop the newest event records until a the tracer releases a + sub-buffer. ++ +This is the only available mode when you specify a +<>. Overwrite mode:: Clear the sub-buffer containing the oldest event records and start @@ -1305,20 +1571,24 @@ always keep a fixed amount of the latest data. Which mechanism you should choose depends on your context: prioritize the newest or the oldest event records in the ring buffer? -Beware that, in overwrite mode, the tracer abandons a whole sub-buffer +Beware that, in overwrite mode, the tracer abandons a _whole sub-buffer_ 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. In overwrite +mode, since LTTng 2.8, LTTng increments a count of lost sub-buffers when +a sub-buffer is lost and saves this count to the trace. In this mode, +the exact number of lost event records in those lost sub-buffers is not +saved to the trace. Trace analyses can use the trace's saved discarded +event record and sub-buffer counts to decide whether or not to perform +the analyses even if trace data is known to be missing. There are a few ways to decrease your probability of losing event records. <> shows -how you can fine-une the sub-buffer count and size of a channel to +how you can fine-tune the sub-buffer count and size of a channel to virtually stop losing event records, though at the cost of greater memory usage. @@ -1528,7 +1798,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)). @@ -1824,7 +2094,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 @@ -4161,7 +4431,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 @@ -5514,6 +5784,11 @@ $ lttng destroy ---- -- +The man:lttng-destroy(1) command also runs the man:lttng-stop(1) +command implicitly (see <>). You need to stop tracing to make LTTng flush the +remaining trace data and make the trace readable. + [[list-instrumentation-points]] === List the available instrumentation points @@ -5598,8 +5873,9 @@ Tracepoint or system call name. In the case of a Linux KProbe or function, this is a custom name given to the event rule. With the JUL, log4j, and Python domains, this is a logger name. -With a tracepoint, logger, or system call name, the last character -can be `*` to match anything that remains. +With a tracepoint, logger, or system call name, you can use the special +`*` globbing character to match anything (for example, `sched_*`, +`my_comp*:*msg_*`). |All. @@ -5861,6 +6137,12 @@ records>> or lost sub-buffers since the last time you ran man:lttng-start(1), warnings are printed when you run the man:lttng-stop(1) command. +IMPORTANT: You need to stop tracing to make LTTng flush the remaining +trace data and make the trace readable. Note that the +man:lttng-destroy(1) command (see +<>) also runs the man:lttng-stop(1) command implicitly. + [[enabling-disabling-channels]] === Create a channel @@ -5950,7 +6232,7 @@ in blocking mode to +__TIMEOUTUS__+: 0 (default):: Never block (non-blocking mode). --1:: +`inf`:: Block forever until space is available in a sub-buffer to record the event. @@ -6019,7 +6301,7 @@ and <>: [role="term"] ---- $ lttng create -$ lttng enable-channel --userspace --blocking-timeout=-1 blocking-channel +$ lttng enable-channel --userspace --blocking-timeout=inf blocking-channel $ lttng enable-event --userspace --channel=blocking-channel --all $ lttng start ---- @@ -6243,8 +6525,8 @@ 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"] ---- @@ -6777,152 +7059,152 @@ disable event rules when this happens. int main(int argc, char *argv[]) { - int exit_status = 0; - struct lttng_notification_channel *notification_channel; - struct lttng_condition *condition; - struct lttng_action *action; - struct lttng_trigger *trigger; - const char *tracing_session_name; - const char *channel_name; - - assert(argc >= 3); - tracing_session_name = argv[1]; - channel_name = argv[2]; - - /* - * Create a notification channel. A notification channel - * connects the user application to the LTTng session daemon. - * This notification channel can be used to listen for various - * types of notifications. - */ - notification_channel = lttng_notification_channel_create( - lttng_session_daemon_notification_endpoint); - - /* - * Create a "high buffer usage" condition. In this case, the - * condition is reached when the buffer usage is greater than or - * equal to 75 %. We create the condition for a specific session - * name, channel name, and for the user space tracing domain. - * - * The "low buffer usage" condition type also exists. - */ - condition = lttng_condition_buffer_usage_high_create(); - lttng_condition_buffer_usage_set_threshold_ratio(condition, .75); - lttng_condition_buffer_usage_set_session_name( - condition, tracing_session_name); - lttng_condition_buffer_usage_set_channel_name(condition, - channel_name); - lttng_condition_buffer_usage_set_domain_type(condition, - LTTNG_DOMAIN_UST); - - /* - * Create an action (get a notification) to take when the - * condition created above is reached. - */ - action = lttng_action_notify_create(); - - /* - * Create a trigger. A trigger associates a condition to an - * action: the action is executed when the condition is reached. - */ - trigger = lttng_trigger_create(condition, action); - - /* Register the trigger to LTTng. */ - lttng_register_trigger(trigger); - - /* - * Now that we have registered a trigger, a notification will be - * emitted everytime its condition is met. To receive this - * notification, we must subscribe to notifications that match - * the same condition. - */ - lttng_notification_channel_subscribe(notification_channel, condition); - - /* - * Notification loop. This can be in a dedicated thread to avoid - * blocking the main thread. - */ - for (;;) { - struct lttng_notification *notification; - enum lttng_notification_channel_status status; - const struct lttng_evaluation *notification_evaluation; - const struct lttng_condition *notification_condition; - double buffer_usage; - - /* Receive the next notification. */ - status = lttng_notification_channel_get_next_notification( - notification_channel, - ¬ification); - - switch (status) { - case LTTNG_NOTIFICATION_CHANNEL_STATUS_OK: - break; - case LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED: - /* - * The session daemon can drop notifications if - * a monitoring application is not consuming the - * notifications fast enough. - */ - continue; - case LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED: - /* - * The notification channel has been closed by the - * session daemon. This is typically caused by a session - * daemon shutting down (cleanly or because of a crash). - */ - goto end; - default: - /* Unhandled conditions or errors. */ - exit_status = 1; - goto end; - } + int exit_status = 0; + struct lttng_notification_channel *notification_channel; + struct lttng_condition *condition; + struct lttng_action *action; + struct lttng_trigger *trigger; + const char *tracing_session_name; + const char *channel_name; + + assert(argc >= 3); + tracing_session_name = argv[1]; + channel_name = argv[2]; /* - * A notification provides, amongst other things: - * - * * The condition that caused this notification to be - * emitted. - * * The condition evaluation, which provides more - * specific information on the evaluation of the - * condition. + * Create a notification channel. A notification channel + * connects the user application to the LTTng session daemon. + * This notification channel can be used to listen to various + * types of notifications. + */ + notification_channel = lttng_notification_channel_create( + lttng_session_daemon_notification_endpoint); + + /* + * Create a "high buffer usage" condition. In this case, the + * condition is reached when the buffer usage is greater than or + * equal to 75 %. We create the condition for a specific tracing + * session name, channel name, and for the user space tracing + * domain. * - * The condition evaluation provides the buffer usage - * value at the moment the condition was met. + * The "low buffer usage" condition type also exists. + */ + condition = lttng_condition_buffer_usage_high_create(); + lttng_condition_buffer_usage_set_threshold_ratio(condition, .75); + lttng_condition_buffer_usage_set_session_name( + condition, tracing_session_name); + lttng_condition_buffer_usage_set_channel_name(condition, + channel_name); + lttng_condition_buffer_usage_set_domain_type(condition, + LTTNG_DOMAIN_UST); + + /* + * Create an action (get a notification) to take when the + * condition created above is reached. */ - notification_condition = lttng_notification_get_condition( - notification); - notification_evaluation = lttng_notification_get_evaluation( - notification); + action = lttng_action_notify_create(); - /* We're subscribed to only one condition. */ - assert(lttng_condition_get_type(notification_condition) == - LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH); + /* + * Create a trigger. A trigger associates a condition to an + * action: the action is executed when the condition is reached. + */ + trigger = lttng_trigger_create(condition, action); + + /* Register the trigger to LTTng. */ + lttng_register_trigger(trigger); /* - * Get the exact sampled buffer usage from the - * condition evaluation. + * Now that we have registered a trigger, a notification will be + * emitted everytime its condition is met. To receive this + * notification, we must subscribe to notifications that match + * the same condition. */ - lttng_evaluation_buffer_usage_get_usage_ratio( - notification_evaluation, &buffer_usage); + lttng_notification_channel_subscribe(notification_channel, + condition); /* - * At this point, instead of printing a message, we - * could do something to reduce the channel's buffer - * usage, like disable specific events. + * Notification loop. You can put this in a dedicated thread to + * avoid blocking the main thread. */ - printf("Buffer usage is %f %% in tracing session \"%s\", " - "user space channel \"%s\".\n", - buffer_usage * 100, tracing_session_name, - channel_name); - lttng_notification_destroy(notification); - } + for (;;) { + struct lttng_notification *notification; + enum lttng_notification_channel_status status; + const struct lttng_evaluation *notification_evaluation; + const struct lttng_condition *notification_condition; + double buffer_usage; + + /* Receive the next notification. */ + status = lttng_notification_channel_get_next_notification( + notification_channel, ¬ification); + + switch (status) { + case LTTNG_NOTIFICATION_CHANNEL_STATUS_OK: + break; + case LTTNG_NOTIFICATION_CHANNEL_STATUS_NOTIFICATIONS_DROPPED: + /* + * The session daemon can drop notifications if + * a monitoring application is not consuming the + * notifications fast enough. + */ + continue; + case LTTNG_NOTIFICATION_CHANNEL_STATUS_CLOSED: + /* + * The notification channel has been closed by the + * session daemon. This is typically caused by a session + * daemon shutting down. + */ + goto end; + default: + /* Unhandled conditions or errors. */ + exit_status = 1; + goto end; + } + + /* + * A notification provides, amongst other things: + * + * * The condition that caused this notification to be + * emitted. + * * The condition evaluation, which provides more + * specific information on the evaluation of the + * condition. + * + * The condition evaluation provides the buffer usage + * value at the moment the condition was reached. + */ + notification_condition = lttng_notification_get_condition( + notification); + notification_evaluation = lttng_notification_get_evaluation( + notification); + + /* We're subscribed to only one condition. */ + assert(lttng_condition_get_type(notification_condition) == + LTTNG_CONDITION_TYPE_BUFFER_USAGE_HIGH); + + /* + * Get the exact sampled buffer usage from the + * condition evaluation. + */ + lttng_evaluation_buffer_usage_get_usage_ratio( + notification_evaluation, &buffer_usage); + + /* + * At this point, instead of printing a message, we + * could do something to reduce the channel's buffer + * usage, like disable specific events. + */ + printf("Buffer usage is %f %% in tracing session \"%s\", " + "user space channel \"%s\".\n", buffer_usage * 100, + tracing_session_name, channel_name); + lttng_notification_destroy(notification); + } end: - lttng_action_destroy(action); - lttng_condition_destroy(condition); - lttng_trigger_destroy(trigger); - lttng_notification_channel_destroy(notification_channel); - return exit_status; + lttng_action_destroy(action); + lttng_condition_destroy(condition); + lttng_trigger_destroy(trigger); + lttng_notification_channel_destroy(notification_channel); + return exit_status; } ---- --