The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.10, 31 July 2017
+v2.10, 3 October 2017
include::../common/copyright.txt[]
[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
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 3 October 2017.
|====
|Distribution |Available in releases |Alternatives
|https://www.ubuntu.com/[Ubuntu]
|Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_:
<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-|link:/docs/v2.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_].
+|link:/docs/v2.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ and Ubuntu{nbsp}17.10 _Artful Aardvark_].
<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Ubuntu releases.
|https://getfedora.org/[Fedora]
-|_Not available_
+|<<fedora,Fedora{nbsp}27>>.
|link:/docs/v2.9#doc-fedora[LTTng{nbsp}2.9 for Fedora 26].
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+other Fedora releases.
|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)].
+|<<debian,Debian "buster" (testing) and Debian "sid" (unstable)>>.
+|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" (stable)].
<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://www.archlinux.org/[Arch Linux]
-|_Not available_
-|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 in the latest AUR packages].
+|<<arch-linux,Current Arch Linux build>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://alpinelinux.org/[Alpine Linux]
|_Not available_
--
+[[fedora]]
+=== Fedora
+
+To install LTTng{nbsp}{revision} on Fedora{nbsp}27:
+
+. 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 <<java-application,Java
+applications>> on Fedora, you need to build and install
+LTTng-UST{nbsp}{revision} <<building-from-source,from source>> 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 <<python-application,Python
+applications>> 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" (testing)
+or Debian "sid" (unstable):
+
+. 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 <<java-application,Java
+ applications>>**, install the LTTng-UST Java agent:
++
+--
+[role="term"]
+----
+# apt-get install liblttng-ust-agent-java
+----
+--
+
+. **If you need to instrument and trace <<python-application,Python
+ applications>>**, install the LTTng-UST Python agent:
++
+--
+[role="term"]
+----
+# apt-get install python3-lttngust
+----
+--
+
+
+[[arch-linux]]
+=== Arch Linux
+
+LTTng-UST{nbsp}{revision} is available in Arch Linux's _Community_
+repository, while LTTng-tools{nbsp}{revision} and
+LTTng-modules{nbsp}{revision} are available in the
+https://aur.archlinux.org/[AUR].
+
+To install LTTng{nbsp}{revision} on Arch Linux, using
+https://github.com/rmarquis/pacaur[pacaur] for the AUR packages:
+
+. Install the main LTTng{nbsp}{revision} packages:
++
+--
+[role="term"]
+----
+# pacman -Sy lttng-ust
+$ pacaur -Sy lttng-tools
+$ pacaur -Sy lttng-modules
+----
+--
+
+. **If you need to instrument and trace <<python-application,Python
+ applications>>**, install the LTTng-UST Python agent:
++
+--
+[role="term"]
+----
+# pacman -Sy python-lttngust
+# pacman -Sy python2-lttngust
+----
+--
+
+
[[enterprise-distributions]]
=== RHEL, SUSE, and other enterprise distributions
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
+<<opt-blocking-timeout,blocking timeout>>.
Overwrite mode::
Clear the sub-buffer containing the oldest event records and start
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.
0 (default)::
Never block (non-blocking mode).
--1::
+`inf`::
Block forever until space is available in a sub-buffer to record
the event.
[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
----
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;
}
----
--