// SPDX-FileCopyrightText: 2017-2023 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

= babeltrace2-filter.utils.trimmer(7)
:manpagetype: component class
:revdate: 1 September 2023


== NAME

babeltrace2-filter.utils.trimmer - Babeltrace 2: Trimmer filter
component class


== DESCRIPTION

A Babeltrace~2 compcls:filter.utils.trimmer message iterator
discards all the consumed messages with a time less than a given
beginning time and greater than a given end time. It effectively
``cuts'', or trims trace streams.

----
            +-------------------+
            | flt.utils.trimmer |
            |                   |
Messages -->@ in            out @--> Less messages
            +-------------------+
----

include::common-see-babeltrace2-intro.txt[]

A compcls:filter.utils.trimmer message iterator makes its upstream
message iterator seek the configured beginning time (see the param:begin
parameter) before it starts to consume messages. This seeking operation
can have an effect on the times of stream beginning, packet beginning,
discarded events, and discarded packets messages so that they fall
within the configured trimming time range.

As such, when a compcls:filter.utils.trimmer message iterator consumes a
message of which the time is greater than the configured end time (see
the param:end parameter), it can alter the time of stream end, packet
end, discarded events, and discarded packets messages so that they fall
within the configured trimming time range.

A compcls:filter.utils.trimmer message iterator requires that all the
upstream messages it consumes have times, except for stream beginning
and end messages, returning an error status otherwise.


== INITIALIZATION PARAMETERS

param:begin='TIME' vtype:[optional string or signed integer]::
    Set the beginning time of the trimming time range to 'TIME'.
+
If 'TIME' is a string, see below for its format. If 'TIME' is a signed
integer, then the component converts it to a string and treats it as
such.
+
If you don't specify this parameter, then the component discards no
events until the end of the trimming time range.
+
The format of 'TIME' when it's a string is one of:
+
--
include::common-trimmer-time-format.txt[]
--
+
If 'TIME' has no date information, then the message iterator uses the
time of the first upstream message to determine the date.

param:end='TIME' vtype:[optional string or signed integer]::
    Set the end time of the trimming time range to 'TIME'.
+
If 'TIME' is a string, see the param:begin parameter for its format. If
'TIME' is a signed integer, then the component converts it to a string
and treats it as such.
+
If you don't specify this parameter, then the component discards no
events from the beginning of the trimming time range.

param:gmt='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then set the time zone of the param:begin and
    param:end parameters to GMT instead of the local time zone.
+
Default: false.


== PORTS

----
+-------------------+
| flt.utils.trimmer |
|                   |
@ in            out @
+-------------------+
----


=== Input

`in`::
    Single input port.


=== Output

`out`::
    Single output port.


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-plugin-utils(7)
