From: Philippe Proulx Date: Fri, 18 Oct 2019 19:29:31 +0000 (-0400) Subject: lttng-rotate.1.txt: update voice and document the `archives` subdir. X-Git-Tag: v2.12.0-rc1~301 X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=adc4b5c84ab187cafb8b5368bdfd4b6be5b1faf5 lttng-rotate.1.txt: update voice and document the `archives` subdir. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt index 85b95fc3a..d197b877b 100644 --- a/doc/man/lttng-rotate.1.txt +++ b/doc/man/lttng-rotate.1.txt @@ -20,11 +20,11 @@ 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 +Once LTTng archives a trace chunk, it 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. +An _archived trace chunk_ is a collection of metadata and data stream +files which form a self-contained LTTng trace. The _current trace chunk_ of a given tracing session includes: @@ -39,28 +39,32 @@ The _current trace chunk_ of a given tracing session includes: * 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. +You can use `lttng rotate`: + +* At any time when the tracing session is active (see + man:lttng-start(1)). +* A single time once the tracing session becomes inactive + (see man:lttng-stop(1)). + +By default, the `lttng rotate` command ensures that LTTng finished +performing the tracing session rotation before it prints the archived +trace chunk's path and exits. 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, so +that LTTng might not have completed the rotation when the command exits. +In this case, there is no easy way to know when the current trace chunk +becomes archived, and the command does not print the archived trace +chunk's path. + +Because when LTTng performs a tracing session rotation, it flushes the +tracing session's current sub-buffers, 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. @@ -68,9 +72,11 @@ 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) and -man:lttng-relayd(8)) which contains, through tracing domain and possibly +A trace chunk archive is a subdirectory of the `archives` subdirectory +within a tracing session's output directory (see the nloption:--output +option in man:lttng-create(1) and man:lttng-relayd(8)). + +A trace chunk archive contains, through tracing domain and possibly UID/PID subdirectories, metadata and data stream files. A trace chunk archive is, at the same time: @@ -83,15 +89,16 @@ 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: +When LTTng performs a tracing session rotation, it names the resulting +trace chunk archive as such, relative to the tracing session's output +directory: [verse] -__BEGIN__-__END__-__ID__ +archives/__BEGIN__-__END__-__ID__ __BEGIN__:: Date and time of the beginning of the trace chunk archive with - the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where + the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the time zone offset from UTC. + @@ -99,17 +106,21 @@ Example: `20171119T152407-0500` __END__:: Date and time of the end of the trace chunk archive with - the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where + the ISO{nbsp}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. + Unique numeric identifier of the trace chunk within its tracing + session. + +Trace chunk archive name example: -Trace chunk archive name example: `20171119T152407-0500-20171119T151422-0500-3` +---- +archives/20171119T152407-0500-20171119T151422-0500-3 +---- include::common-cmd-options-head.txt[]