The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.10, 31 July 2017
+v2.10, 1 August 2017
include::../common/copyright.txt[]
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.
/*
* 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
+ * This notification channel can be used to listen to various
* types of notifications.
*/
notification_channel = lttng_notification_channel_create(
/*
* 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.
+ * equal to 75 %. We create the condition for a specific tracing
+ * session name, channel name, and for the user space tracing
+ * domain.
*
* The "low buffer usage" condition type also exists.
*/
* notification, we must subscribe to notifications that match
* the same condition.
*/
- lttng_notification_channel_subscribe(notification_channel, condition);
+ lttng_notification_channel_subscribe(notification_channel,
+ condition);
/*
- * Notification loop. This can be in a dedicated thread to avoid
- * blocking the main thread.
+ * Notification loop. You can put this in a dedicated thread to
+ * avoid blocking the main thread.
*/
for (;;) {
struct lttng_notification *notification;
/* Receive the next notification. */
status = lttng_notification_channel_get_next_notification(
- notification_channel,
- ¬ification);
+ notification_channel, ¬ification);
switch (status) {
case LTTNG_NOTIFICATION_CHANNEL_STATUS_OK:
* condition.
*
* The condition evaluation provides the buffer usage
- * value at the moment the condition was met.
+ * value at the moment the condition was reached.
*/
notification_condition = lttng_notification_get_condition(
notification);
* 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);
+ "user space channel \"%s\".\n", buffer_usage * 100,
+ tracing_session_name, channel_name);
lttng_notification_destroy(notification);
}