2.8, 2.9, 2.10: since 2.8, LTTng keeps lost sub-buffer count in overwrite mode

[lttng-docs.git] / 2.10 / lttng-docs-2.10.txt

diff --git a/2.10/lttng-docs-2.10.txt b/2.10/lttng-docs-2.10.txt
index 58bbdf5967130f64fac218369451b08c4791c262..10d1f443d4a38edc0d0684ed4501a9d54c9e46c6 100644 (file)
--- a/2.10/lttng-docs-2.10.txt
+++ b/2.10/lttng-docs-2.10.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
-v2.10, 31 July 2017
+v2.10, 1 August 2017
 
 
 include::../common/copyright.txt[]
@@ -1290,8 +1290,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
+<<opt-blocking-timeout,blocking timeout>>.
 
 Overwrite mode::
   Clear the sub-buffer containing the oldest event records and start
@@ -1305,15 +1308,19 @@ 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.
@@ -6792,7 +6799,7 @@ int main(int argc, char *argv[])
     /*
      * 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(
@@ -6801,8 +6808,9 @@ int main(int argc, char *argv[])
     /*
      * 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.
      */
@@ -6836,11 +6844,12 @@ int main(int argc, char *argv[])
      * 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;
@@ -6851,8 +6860,7 @@ int main(int argc, char *argv[])
 
         /* Receive the next notification. */
         status = lttng_notification_channel_get_next_notification(
-            notification_channel,
-            &notification);
+            notification_channel, &notification);
 
         switch (status) {
         case LTTNG_NOTIFICATION_CHANNEL_STATUS_OK:
@@ -6887,7 +6895,7 @@ int main(int argc, char *argv[])
          *   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);
@@ -6911,9 +6919,8 @@ int main(int argc, char *argv[])
          * 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);
     }