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

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