doc/man/lttng-enable-rotation.1.txt

   1 lttng-enable-rotation(1)
   2 ========================
   3 :revdate: 3 May 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-enable-rotation - Set an LTTng tracing session rotation schedule
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
  15       (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE')
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng enable-rotation` command sets a tracing session rotation
  21 schedule for:
  22
  23 With the option:--session='SESSION' option::
  24     The tracing session named 'SESSION'.
  25
  26 Without the option:--session option::
  27     The current tracing session (see man:lttng-concepts(7) to learn more
  28     about the current tracing session).
  29
  30 See man:lttng-concepts(7) to learn more about the tracing session
  31 rotation and trace chunk concepts.
  32
  33 With the option:--timer='PERIODUS' option, the `enable-rotation` command
  34 sets a rotation schedule so that LTTng performs an automatic rotation at
  35 least every 'PERIODUS'.
  36
  37 With the option:--size='SIZE' option, the `enable-rotation` command sets
  38 a rotation schedule so that LTTng performs an automatic rotation every
  39 time the total size of the flushed part of the current trace chunk is at
  40 least 'SIZE'.
  41
  42 For both the option:--timer and option:--size options, LTTng checks the
  43 schedule condition periodically using the monitor timers of the channels
  44 of the selected tracing session (see the nloption:--monitor-timer option
  45 of the man:lttng-enable-channel(1) command). This means that:
  46
  47 * With the option:--timer='PERIODUS' option, LTTng can perform an
  48   automatic rotation when the elapsed time since the last automatic
  49   rotation is slightly greater than 'PERIODUS'.
  50 +
  51 The exact precision depends on the precision of the monitor timer, which
  52 relies on the precision of the platform implementation of POSIX timers.
  53
  54 * With the option:--size='SIZE' option, LTTng can perform an automatic
  55   rotation when the size of the flushed part of the current trace chunk
  56   is greater than 'SIZE'.
  57
  58 You may combine the option:--timer and option:--size options.
  59
  60 See the man:lttng-concepts(7) to learn how LTTng names a trace chunk
  61 archive directory.
  62
  63 Unset a tracing session rotation schedule with the
  64 man:lttng-disable-rotation(1) command.
  65
  66 [IMPORTANT]
  67 ====
  68 You may only use the `enable-rotation` command when:
  69
  70 * The selected tracing session was created in normal mode or in network
  71   streaming mode (see man:lttng-create(1)).
  72
  73 * No channel was created with a configured trace file count or size
  74   limit (see the nloption:--tracefile-size and
  75   nloption:--tracefile-count options of the man:lttng-enable-channel(1)
  76   command).
  77
  78 For a given tracing session, LTTng only performs an automatic rotation
  79 when it's not currently performing a rotation.
  80 ====
  81
  82
  83 include::common-cmd-options-head.txt[]
  84
  85
  86 Rotation schedule condition
  87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88 option:--size='SIZE'::
  89     Set a rotation schedule so that LTTng performs an automatic rotation
  90     every time the total size of the flushed part of the current trace
  91     chunk is at least 'SIZE' bytes.
  92 +
  93 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
  94 supported.
  95
  96 option:--timer='PERIODUS'::
  97     Set a rotation schedule so that LTTng performs an automatic rotation
  98     approximately every 'PERIODUS' microseconds.
  99 +
 100 The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
 101 and `h`{nbsp}(hours) suffixes are supported.
 102
 103
 104 Recording target
 105 ~~~~~~~~~~~~~~~~
 106 option:-s 'SESSION', option:--session='SESSION'::
 107     Set a rotation schedule for the tracing session named 'SESSION'
 108     instead of the current tracing session.
 109
 110
 111 include::common-cmd-help-options.txt[]
 112
 113
 114 include::common-cmd-footer.txt[]
 115
 116
 117 SEE ALSO
 118 --------
 119 man:lttng(1),
 120 man:lttng-concepts(7),
 121 man:lttng-create(1),
 122 man:lttng-disable-rotation(1),
 123 man:lttng-rotate(1)