doc/man/babeltrace2-filter.utils.trimmer.7.txt

   1 = babeltrace2-filter.utils.trimmer(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   4
   5
   6 == NAME
   7
   8 babeltrace2-filter.utils.trimmer - Babeltrace 2's trimmer filter
   9 component class
  10
  11
  12 == DESCRIPTION
  13
  14 A Babeltrace~2 compcls:filter.utils.trimmer message iterator
  15 discards all the consumed messages with a time less than a given
  16 beginning time and greater than a given end time. It effectively
  17 ``cuts'', or trims trace streams.
  18
  19 ----
  20             +-------------------+
  21             | flt.utils.trimmer |
  22             |                   |
  23 Messages -->@ in            out @--> Less messages
  24             +-------------------+
  25 ----
  26
  27 include::common-see-babeltrace2-intro.txt[]
  28
  29 A compcls:filter.utils.trimmer message iterator makes its upstream
  30 message iterator seek the configured beginning time (see the param:begin
  31 parameter) before it starts to consume messages. This seeking operation
  32 can have an effect on the times of stream beginning, packet beginning,
  33 discarded events, and discarded packets messages so that they fall
  34 within the configured trimming time range.
  35
  36 As such, when a compcls:filter.utils.trimmer message iterator consumes a
  37 message of which the time is greater than the configured end time (see
  38 the param:end parameter), it can alter the time of stream end, packet
  39 end, discarded events, and discarded packets messages so that they fall
  40 within the configured trimming time range.
  41
  42 A compcls:filter.utils.trimmer message iterator requires that all the
  43 upstream messages it consumes have times, except for stream beginning
  44 and end messages, returning an error status otherwise.
  45
  46
  47 == INITIALIZATION PARAMETERS
  48
  49 param:begin='TIME' vtype:[optional string or signed integer]::
  50     Set the trimming time range's beginning time to 'TIME'.
  51 +
  52 If 'TIME' is a string, see below for its format. If 'TIME' is a signed
  53 integer, the component converts it to a string and treats it as such.
  54 +
  55 If you don't specify this parameter, the component discards no events
  56 until the end of the trimming time range.
  57 +
  58 The format of 'TIME' when it's a string is one of:
  59 +
  60 --
  61 include::common-trimmer-time-format.txt[]
  62 --
  63 +
  64 If 'TIME' has no date information, then the message iterator uses the
  65 first upstream message's time to determine the date.
  66
  67 param:end='TIME' vtype:[optional string or signed integer]::
  68     Set the trimming time range's end time to 'TIME'.
  69 +
  70 If 'TIME' is a string, see the param:begin parameter for its format. If
  71 'TIME' is a signed integer, the component converts it to a string and
  72 treats it as such.
  73 +
  74 If you don't specify this parameter, the component discards no events
  75 from the beginning of the trimming time range.
  76
  77 param:gmt=`yes` vtype:[optional boolean]::
  78     Set the time zone of the param:begin and param:end parameters
  79     to GMT instead of the local time zone.
  80
  81
  82 == PORTS
  83
  84 ----
  85 +-------------------+
  86 | flt.utils.trimmer |
  87 |                   |
  88 @ in            out @
  89 +-------------------+
  90 ----
  91
  92
  93 === Input
  94
  95 `in`::
  96     Single input port.
  97
  98
  99 === Output
 100
 101 `out`::
 102     Single output port.
 103
 104
 105 include::common-footer.txt[]
 106
 107
 108 == SEE ALSO
 109
 110 man:babeltrace2-intro(7),
 111 man:babeltrace2-plugin-utils(7)