Commit | Line | Data |
---|---|---|
2facbdc3 | 1 | = babeltrace2-filter.utils.trimmer(7) |
838dd456 | 2 | :manpagetype: component class |
2facbdc3 | 3 | :revdate: 14 September 2019 |
838dd456 PP |
4 | |
5 | ||
2facbdc3 | 6 | == NAME |
838dd456 | 7 | |
2facbdc3 PP |
8 | babeltrace2-filter.utils.trimmer - Babeltrace 2's trimmer filter |
9 | component class | |
838dd456 | 10 | |
838dd456 | 11 | |
2facbdc3 | 12 | == DESCRIPTION |
838dd456 | 13 | |
2facbdc3 PP |
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. | |
838dd456 | 18 | |
2facbdc3 PP |
19 | ---- |
20 | +-------------------+ | |
21 | | flt.utils.trimmer | | |
22 | | | | |
23 | Messages -->@ in out @--> Less messages | |
24 | +-------------------+ | |
25 | ---- | |
838dd456 | 26 | |
2facbdc3 | 27 | include::common-see-babeltrace2-intro.txt[] |
838dd456 | 28 | |
2facbdc3 PP |
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. | |
838dd456 | 35 | |
2facbdc3 PP |
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. | |
838dd456 | 41 | |
2facbdc3 PP |
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. | |
838dd456 PP |
45 | |
46 | ||
2facbdc3 | 47 | == INITIALIZATION PARAMETERS |
838dd456 | 48 | |
2facbdc3 PP |
49 | param:begin='TIME' vtype:[optional string or signed integer]:: |
50 | Set the trimming time range's beginning time to 'TIME'. | |
838dd456 | 51 | + |
2facbdc3 PP |
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. | |
838dd456 PP |
54 | + |
55 | If you don't specify this parameter, the component discards no events | |
2facbdc3 PP |
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. | |
838dd456 | 66 | |
2facbdc3 PP |
67 | param:end='TIME' vtype:[optional string or signed integer]:: |
68 | Set the trimming time range's end time to 'TIME'. | |
838dd456 | 69 | + |
2facbdc3 PP |
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. | |
838dd456 PP |
73 | + |
74 | If you don't specify this parameter, the component discards no events | |
2facbdc3 | 75 | from the beginning of the trimming time range. |
838dd456 | 76 | |
2facbdc3 PP |
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. | |
838dd456 | 80 | |
838dd456 | 81 | |
2facbdc3 PP |
82 | == PORTS |
83 | ||
84 | ---- | |
85 | +-------------------+ | |
86 | | flt.utils.trimmer | | |
87 | | | | |
88 | @ in out @ | |
89 | +-------------------+ | |
90 | ---- | |
838dd456 | 91 | |
838dd456 | 92 | |
2facbdc3 | 93 | === Input |
838dd456 | 94 | |
2facbdc3 PP |
95 | `in`:: |
96 | Single input port. | |
838dd456 PP |
97 | |
98 | ||
2facbdc3 | 99 | === Output |
838dd456 | 100 | |
2facbdc3 PP |
101 | `out`:: |
102 | Single output port. | |
838dd456 PP |
103 | |
104 | ||
105 | include::common-footer.txt[] | |
106 | ||
107 | ||
2facbdc3 PP |
108 | == SEE ALSO |
109 | ||
110 | man:babeltrace2-intro(7), | |
111 | man:babeltrace2-plugin-utils(7) |