Document tracing session rotation features
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Thu, 18 Jan 2018 22:12:02 +0000 (17:12 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Tue, 3 Apr 2018 16:12:29 +0000 (12:12 -0400)
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
12 files changed:
configure.ac
doc/man/Makefile.am
doc/man/asciidoc-attrs.conf.in
doc/man/lttng-create.1.txt
doc/man/lttng-destroy.1.txt
doc/man/lttng-disable-rotation.1.txt [new file with mode: 0644]
doc/man/lttng-enable-channel.1.txt
doc/man/lttng-enable-rotation.1.txt [new file with mode: 0644]
doc/man/lttng-regenerate.1.txt
doc/man/lttng-rotate.1.txt [new file with mode: 0644]
doc/man/lttng-stop.1.txt
doc/man/lttng.1.txt

index 71ec278036b1a5b23fbc25fc827a478e8eb927e5..00ffd680b61b8596c40991c30006d4f8b047692c 100644 (file)
@@ -373,12 +373,15 @@ _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Tear down tracing sessions])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable tracing channels])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_EVENT], [Disable event rules])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset an automatic rotation schedule])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_CHANNEL], [Create or enable tracing channels])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_EVENT], [Create or enable event rules])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set an automatic rotation schedule])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_HELP], [Display help information about a command])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing sessions, domains, channels, and events])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load tracing session configurations])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Manage an LTTng tracing session's data regeneration])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive a tracing session's current trace chunk])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save tracing session configurations])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set current tracing session])
 _AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Snapshot buffers of current tracing session])
index eb88e86d8cc8f26d1fa81ce55c5fb970290c8bd2..ccd76f74605e9907b14411a147b3fc24ab975d61 100644 (file)
@@ -30,7 +30,10 @@ MAN1_NAMES = \
        lttng-disable-event \
        lttng-crash \
        lttng-metadata \
-       lttng-regenerate
+       lttng-regenerate \
+       lttng-rotate \
+       lttng-enable-rotation \
+       lttng-disable-rotation
 MAN3_NAMES =
 MAN8_NAMES = lttng-sessiond lttng-relayd
 MAN1_NO_ASCIIDOC_NAMES =
index bf6333c9127152f7f4ffadb44c4063d729b8182e..35453900159386d1d60ce6fb283a89a43c5f23b7 100644 (file)
@@ -47,12 +47,15 @@ cmd_descr_create="@CMD_DESCR_CREATE@"
 cmd_descr_destroy="@CMD_DESCR_DESTROY@"
 cmd_descr_disable_channel="@CMD_DESCR_DISABLE_CHANNEL@"
 cmd_descr_disable_event="@CMD_DESCR_DISABLE_EVENT@"
+cmd_descr_disable_rotation="@CMD_DESCR_DISABLE_ROTATION@"
 cmd_descr_enable_channel="@CMD_DESCR_ENABLE_CHANNEL@"
 cmd_descr_enable_event="@CMD_DESCR_ENABLE_EVENT@"
+cmd_descr_enable_rotation="@CMD_DESCR_ENABLE_ROTATION@"
 cmd_descr_help="@CMD_DESCR_HELP@"
 cmd_descr_list="@CMD_DESCR_LIST@"
 cmd_descr_load="@CMD_DESCR_LOAD@"
 cmd_descr_regenerate="@CMD_DESCR_REGENERATE@"
+cmd_descr_rotate="@CMD_DESCR_ROTATE@"
 cmd_descr_save="@CMD_DESCR_SAVE@"
 cmd_descr_set_session="@CMD_DESCR_SET_SESSION@"
 cmd_descr_snapshot="@CMD_DESCR_SNAPSHOT@"
index 152e3f39364ee8f5e8795fa8baf2bbcb3feb4ba5..35c6345608f035c10aca5c59864e73cbbad1581f 100644 (file)
@@ -20,6 +20,7 @@ Network streaming mode:
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
       (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
+
 Snapshot mode:
 
 [verse]
index 4b3f4f00e213989aa74d51f4b15f14a1463d575d..1e7ecade209124078a0ed020222a3cb865602aa7 100644 (file)
@@ -40,6 +40,13 @@ Destroying a tracing session does not destroy the recorded trace data,
 if any; it frees resources acquired by the session daemon and tracer
 side, making sure to flush all trace data.
 
+If at least one rotation occurred during the chosen tracing session's
+lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), and
+without the option:--no-wait option, all the tracing session's output
+directory's subdirectories are considered trace chunk archives once the
+command returns: it is safe to read them, modify them, move them, or
+remove them.
+
 
 include::common-cmd-options-head.txt[]
 
diff --git a/doc/man/lttng-disable-rotation.1.txt b/doc/man/lttng-disable-rotation.1.txt
new file mode 100644 (file)
index 0000000..1a9e14e
--- /dev/null
@@ -0,0 +1,73 @@
+lttng-disable-rotation(1)
+=========================
+
+
+NAME
+----
+lttng-disable-rotation - Unset a tracing session's automatic rotation schedule
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-rotation* (option:--timer | option:--size)
+      [option:--session='SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng disable-rotation` command unsets an automatic rotation
+schedule for the current tracing session, or for the tracing session
+named 'SESSION' if provided, previously set with the
+man:lttng-enable-rotation(1) command.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Automatic rotation schedule condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+One of:
+
+option:--size::
+    Unset the automatic rotation schedule previously set with the
+    nloption:--size option of the man:lttng-enable-rotation(1) command.
+
+option:--timer::
+    Unset the automatic rotation schedule previously set with the
+    nloption:--timer option of the man:lttng-enable-rotation(1) command.
+
+
+Target
+~~~~~~
+option:-s 'SESSION', option:--session='SESSION'::
+    Unset an automatic rotation schedule in the tracing session named
+    'SESSION' instead of the current tracing session.
+
+
+include::common-cmd-help-options.txt[]
+
+
+[[limitations]]
+LIMITATIONS
+-----------
+The `lttng enable-rotation` command only works when:
+
+* The tracing session is created in normal mode or in network streaming
+  mode (see man:lttng-create(1)).
+
+* No channel was created with a configured trace file count or size
+  limit (see the nloption:--tracefile-size and
+  nloption:--tracefile-count options in man:lttng-enable-channel(1)).
+
+For a given tracing session, LTTng only performs an automatic rotation
+when no other rotation is currently happening.
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:lttng-enable-rotation(1),
+man:lttng(1)
index 787666ad5d1969d3f23598f1015c631443a8a99e..95e62e6f1ec069f0438033725433502ad173d2d9 100644 (file)
@@ -244,6 +244,14 @@ Here, for each stream, the maximum size of each trace file is
 no space left in the last file, _trace file rotation_ happens: the first
 file is cleared and new sub-buffers containing events are written there.
 
+LTTng does not guarantee that you can view the trace of an active
+tracing session (before you run the man:lttng-stop(1) command), even
+with multiple trace files, because LTTng could overwrite them at any
+moment, or some of them could be incomplete. You can archive a
+tracing session's current trace chunk while the tracing session is
+active to obtain an unmanaged and self-contained LTTng trace: see
+man:lttng-rotate(1) and man:lttng-enable-rotation(1).
+
 
 include::common-cmd-options-head.txt[]
 
diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt
new file mode 100644 (file)
index 0000000..ad753d0
--- /dev/null
@@ -0,0 +1,110 @@
+lttng-enable-rotation(1)
+========================
+
+
+NAME
+----
+lttng-enable-rotation - Set a tracing session's automatic rotation schedule
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* (option:--timer='PERIOD' | option:--size='SIZE')
+      [option:--session='SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng enable-rotation` command sets an automatic rotation schedule
+for the current tracing session, or for the tracing session named
+'SESSION' if provided. See man:lttng-rotate(1) for more information
+about the concepts of a tracing session _rotation_ and a _trace chunk_.
+
+With the option:--timer option, the rotation schedule is set so that an
+automatic rotation occurs at least every 'PERIOD' (microseconds without
+a unit suffix).
+
+With the option:--size option, the rotation schedule is set
+so that an automatic rotation occurs every time the total size of the
+flushed part of the current trace chunk is at least 'SIZE' (bytes
+without a unit suffix).
+
+With both the option:--timer and option:--size options, LTTng checks the
+schedule condition periodically using the monitor timers of the tracing
+session's channels. This means that, with the option:--timer option, the
+automatic rotation can occur when the elapsed time since the last
+automatic rotation is greater than 'PERIOD', and with the option:--size
+option, the automatic rotation can occur when the size of the flushed
+part of the current trace chunk is greater than 'SIZE'. See the
+nloption:--monitor-timer option in man:lttng-enable-channel(1) for more
+information about the monitor timer.
+
+The naming convention of a trace chunk archive which an automatic
+rotation creates is the same as with the manual rotation command,
+man:lttng-rotate(1).
+
+For a given tracing session, you cannot set multiple automatic rotation
+schedules with the option:--timer or the option:--size option.
+
+You can unset an automatic rotation schedule with the
+man:lttng-disable-rotation(1) command.
+
+See <<limitations,LIMITATIONS>> for important limitations regarding
+this command.
+
+
+include::common-cmd-options-head.txt[]
+
+
+Automatic rotation schedule condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+One of:
+
+option:--size='SIZE'::
+    Set an automatic rotation schedule so that an automatic rotation
+    occurs every time the total size of the flushed part of the current
+    trace chunk is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and
+    `G` (GiB) suffixes are supported.
+
+option:--timer='PERIOD'::
+    Set an automatic rotation schedule so that an automatic rotation
+    occurs at least every 'PERIOD' microseconds. The
+    `ms` (milliseconds), `s` (seconds), `m` (minutes), and `h` (hours)
+    suffixes are supported.
+
+
+Target
+~~~~~~
+option:-s 'SESSION', option:--session='SESSION'::
+    Set an automatic rotation schedule for the tracing session named
+    'SESSION' instead of the current tracing session.
+
+
+include::common-cmd-help-options.txt[]
+
+
+[[limitations]]
+LIMITATIONS
+-----------
+The `lttng enable-rotation` command only works when:
+
+* The tracing session is created in normal mode or in network streaming
+  mode (see man:lttng-create(1)).
+
+* No channel was created with a configured trace file count or size
+  limit (see the nloption:--tracefile-size and
+  nloption:--tracefile-count options in man:lttng-enable-channel(1)).
+
+For a given tracing session, LTTng only performs an automatic rotation
+when no other rotation is currently happening.
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:lttng-rotate(1),
+man:lttng-disable-rotation(1),
+man:lttng(1)
index fd306ad8099f766b084a99d7e456a68ed52d4123..2b19515018133126323ce7cae879e9452a269507 100644 (file)
@@ -39,6 +39,10 @@ wall time is NTP-corrected. Regenerating the tracing session's metadata ensures
 that trace viewers can accurately determine the events time relative to Unix
 Epoch.
 
+If you use man:lttng-rotate(1) or man:lttng-enable-rotation(1) to make
+tracing session rotations, this action regenerates the current and
+next trace chunks's metadata files.
+
 
 Regenerating a tracing session's state dump
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt
new file mode 100644 (file)
index 0000000..f290cae
--- /dev/null
@@ -0,0 +1,161 @@
+lttng-rotate(1)
+===============
+
+
+NAME
+----
+lttng-rotate - Archive a tracing session's current trace chunk
+
+
+SYNOPSIS
+--------
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *rotate* [option:--no-wait] ['SESSION']
+
+
+DESCRIPTION
+-----------
+The `lttng rotate` command archives the current trace chunk of the
+current tracing session, or of the tracing session named 'SESSION' if
+provided, to the file system. This action is called a tracing session
+_rotation_.
+
+Once a trace chunk is archived, LTTng does not manage it anymore: you
+can read it, modify it, move it, or remove it.
+
+An archived trace chunk is a collection of metadata and data stream
+files which form a self-contained trace.
+
+The _current trace chunk_ of a given tracing session includes:
+
+* The stream files already written to the file system, and which are
+  not part of a previously archived trace chunk, since the most recent
+  event amongst:
+** The first time the tracing session was started with
+   man:lttng-start(1).
+** The last rotation, either a manual one with `lttng rotate`, or an
+   automatic one from a rotation schedule previously set with
+   man:lttng-enable-rotation(1).
+* The content of all the non-flushed sub-buffers of the tracing
+  session's channels.
+
+You can use `lttng rotate` either at any time when the tracing session
+is active (see man:lttng-start(1)), or a single time once the tracing
+session becomes inactive (see man:lttng-stop(1)).
+
+By default, the `lttng rotate` command ensures that the rotation is done
+before printing the archived trace chunk's path and returning to the
+prompt. The printed path is absolute when the tracing session was
+created in normal mode and relative to the relay daemon's output
+directory (see the nloption:--output option in man:lttng-relayd(8)) when
+it was created in network streaming mode (see man:lttng-create(1)).
+
+With the option:--no-wait option, the command finishes immediately,
+hence a rotation might not be completed when the command is done. In
+this case, there is no easy way to know when the current trace chunk is
+archived, and the command does not print the archived trace chunk's
+path.
+
+Because a rotation causes the tracing session's current sub-buffers to
+be flushed, archived trace chunks are never redundant, that is, they do
+not overlap over time like snapshots can (see man:lttng-snapshot(1)).
+Also, a rotation does not directly cause discarded event records or
+packets.
+
+See <<limitations,LIMITATIONS>> for important limitations regarding
+this command.
+
+
+Trace chunk archive naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+A trace chunk archive is a subdirectory of a tracing session's output
+directory (see the nloption:--output option in man:lttng-create(1))
+which contains, through tracing domain and possibly UID/PID
+subdirectories, metadata and data stream files.
+
+A trace chunk archive is, at the same time:
+
+* A self-contained LTTng trace.
+* A member of a set of trace chunk archives which form the complete
+  trace of a tracing session.
+
+In other words, an LTTng trace reader can read both the tracing
+session output directory (all the trace chunk archives), or a
+single trace chunk archive.
+
+When a tracing session rotation occurs, the created trace chunk
+archive is named:
+
+[verse]
+__BEGIN__-__END__-__ID__
+
+__BEGIN__::
+    Date and time of the beginning of the trace chunk archive with
+    the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
+    `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
+    time zone offset from UTC.
++
+Example: `20171119T152407-0500`
+
+__END__::
+    Date and time of the end of the trace chunk archive with
+    the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
+    `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
+    time zone offset from UTC.
++
+Example: `20180118T152407+0930`
+
+__ID__::
+    Unique numeric identifier of the trace chunk within its
+    tracing session.
+
+Trace chunk archive name example: `20171119T152407-0500-20171119T151422-0500-3`
+
+
+include::common-cmd-options-head.txt[]
+
+
+option:-n, option:--no-wait::
+    Do not ensure that the rotation is done before returning to
+    the prompt.
+
+
+include::common-cmd-help-options.txt[]
+
+
+[[limitations]]
+LIMITATIONS
+-----------
+The `lttng rotate` command only works when:
+
+* The tracing session is created in normal mode or in network streaming
+  mode (see man:lttng-create(1)).
+
+* No channel was created with a configured trace file count or size
+  limit (see the nloption:--tracefile-size and
+  nloption:--tracefile-count options in man:lttng-enable-channel(1)).
+
+* No manual rotation (`lttng rotate`) is currently happening.
+
+* No automatic rotation schedule is currently set (see
+  man:lttng-enable-rotation(1)).
++
+One way around this is to:
++
+--
+. Unset any automatic rotation schedule with
+  man:lttng-disable-rotation(1).
+. Perform the manual rotation with `lttng rotation`.
+. **If needed**, set the rotation schedule again
+  with man:lttng-enable-rotation(1).
+--
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:lttng-enable-rotation(1),
+man:lttng-disable-rotation(1),
+man:lttng(1)
index 8e71529df14ee805583b64a5270db02b9f5309d3..aafde32d88f0663e0a03fa6529523cbe4b7d87b5 100644 (file)
@@ -38,6 +38,15 @@ option:--no-wait option, the command finishes immediately, hence a local
 trace might not be valid when the command is done. In this case, there
 is no way to know when the trace becomes valid.
 
+If at least one rotation occurred during the chosen tracing session's
+lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), the
+`lttng stop` command renames the current trace chunk subdirectory and
+prints the renamed path. Although it is safe to read the content of this
+renamed subdirectory while the tracing session remains inactive (until
+the next man:lttng-start(1)), it is :not: a trace chunk archive: you
+need to destroy the tracing session with man:lttng-destroy(1) or make
+a rotation with man:lttng-rotate(1) to archive it.
+
 
 include::common-cmd-options-head.txt[]
 
index 9ff407094b79190df063efe29ef8bd9c213fb55f..5e949e20d9f8ea2ed1b95d1d714cbc9ae319e826 100644 (file)
@@ -208,6 +208,19 @@ man:lttng-stop(1)::
     {cmd_descr_stop}.
 
 
+Tracing session rotation
+~~~~~~~~~~~~~~~~~~~~~~~~
+man:lttng-disable-rotation(1)::
+    {cmd_descr_disable_rotation}.
+
+man:lttng-enable-rotation(1)::
+    {cmd_descr_enable_rotation}.
+
+man:lttng-rotate(1)::
+    {cmd_descr_rotate}.
+
+
+
 Resource tracking
 ~~~~~~~~~~~~~~~~~
 man:lttng-track(1)::
This page took 0.046205 seconds and 4 git commands to generate.