lttng-rotate(1) =============== :revdate: 18 October 2019 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 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 LTTng 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 an immediate 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`: * 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. Trace chunk archive naming ~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: * 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 LTTng performs a tracing session rotation, it names the resulting trace chunk archive as such, relative to the tracing session's output directory: [verse] archives/__BEGIN__-__END__-__ID__ __BEGIN__:: Date and time of the beginning of the trace chunk archive with 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: `20171119T152407-0500` __END__:: Date and time of the end of the trace chunk archive with 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. Trace chunk archive name example: ---- archives/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 immediate rotation (`lttng rotate`) is currently happening. include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng-enable-rotation(1), man:lttng-disable-rotation(1), man:lttng(1)