From 980bb5fda2120f8d2a4e82fcf72be7cbbeb85fd2 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Thu, 18 Jan 2018 17:12:02 -0500 Subject: [PATCH] Document tracing session rotation features MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- configure.ac | 3 + doc/man/Makefile.am | 5 +- doc/man/asciidoc-attrs.conf.in | 3 + doc/man/lttng-create.1.txt | 1 + doc/man/lttng-destroy.1.txt | 7 ++ doc/man/lttng-disable-rotation.1.txt | 73 ++++++++++++ doc/man/lttng-enable-channel.1.txt | 8 ++ doc/man/lttng-enable-rotation.1.txt | 110 ++++++++++++++++++ doc/man/lttng-regenerate.1.txt | 4 + doc/man/lttng-rotate.1.txt | 161 +++++++++++++++++++++++++++ doc/man/lttng-stop.1.txt | 9 ++ doc/man/lttng.1.txt | 13 +++ 12 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 doc/man/lttng-disable-rotation.1.txt create mode 100644 doc/man/lttng-enable-rotation.1.txt create mode 100644 doc/man/lttng-rotate.1.txt diff --git a/configure.ac b/configure.ac index 71ec27803..00ffd680b 100644 --- a/configure.ac +++ b/configure.ac @@ -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]) diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index eb88e86d8..ccd76f746 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -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 = diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index bf6333c91..354539001 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -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@" diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index 152e3f393..35c634560 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -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] diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index 4b3f4f00e..1e7ecade2 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -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 index 000000000..1a9e14ef0 --- /dev/null +++ b/doc/man/lttng-disable-rotation.1.txt @@ -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) diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index 787666ad5..95e62e6f1 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -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 index 000000000..ad753d0c9 --- /dev/null +++ b/doc/man/lttng-enable-rotation.1.txt @@ -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 <> 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) diff --git a/doc/man/lttng-regenerate.1.txt b/doc/man/lttng-regenerate.1.txt index fd306ad80..2b1951501 100644 --- a/doc/man/lttng-regenerate.1.txt +++ b/doc/man/lttng-regenerate.1.txt @@ -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 index 000000000..f290cae31 --- /dev/null +++ b/doc/man/lttng-rotate.1.txt @@ -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 <> 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) diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt index 8e71529df..aafde32d8 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -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[] diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 9ff407094..5e949e20d 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -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):: -- 2.34.1