X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fman%2Fbabeltrace2-filter.utils.trimmer.7.txt;h=b1f754e5810c64eb3efcefbbcae4e919beaf2f83;hb=e70712b34fcae860414660c6b10451f57b50c25d;hp=cf49d9c53879bc3fe69277668718ea202d046f5f;hpb=0713ec72ea9f82718c4d54324d6f80eec9c357e0;p=babeltrace.git diff --git a/doc/man/babeltrace2-filter.utils.trimmer.7.txt b/doc/man/babeltrace2-filter.utils.trimmer.7.txt index cf49d9c5..b1f754e5 100644 --- a/doc/man/babeltrace2-filter.utils.trimmer.7.txt +++ b/doc/man/babeltrace2-filter.utils.trimmer.7.txt @@ -1,125 +1,111 @@ -babeltrace2-filter.utils.trimmer(7) -================================== += babeltrace2-filter.utils.trimmer(7) :manpagetype: component class -:revdate: 5 October 2017 +:revdate: 14 September 2019 -NAME ----- -babeltrace2-filter.utils.trimmer - Babeltrace's trimmer filter -component class - - -DESCRIPTION ------------ -The Babeltrace compcls:filter.utils.trimmer component class, provided by -the man:babeltrace2-plugin-utils(7) plugin, once instantiated, discards -all the received events with a time less than a given beginning time and -greater than a given end time. It effectively ``cuts'', or trims traces. - -A compcls:filter.utils.trimmer component modifies the `timestamp_begin` -and `timestamp_end` fields of the packet contexts it receives to match -the beggining and end times of the trimming range when needed. - -The component used a notification's clock value with the highest -priority to decide whether to discard it or not. - +== NAME -[[time-param-fmt]] -Time parameter format -~~~~~~~~~~~~~~~~~~~~~ -The format of the param:begin and param:end parameters is: +babeltrace2-filter.utils.trimmer - Babeltrace 2's trimmer filter +component class -[verse] -$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__] -'YYYY':: - 4-digit year. +== DESCRIPTION -'MM':: - 2-digit month (January is `01`). +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. -'DD':: - 2-digit day. +---- + +-------------------+ + | flt.utils.trimmer | + | | +Messages -->@ in out @--> Less messages + +-------------------+ +---- -'hh':: - 2-digit hour (24-hour format). +include::common-see-babeltrace2-intro.txt[] -'mm':: - 2-digit minute. +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. -'ss':: - 2-digit second. +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. -'nnnnnnnnn':: - 9-digit nanosecond. +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 -------------------------- -You must specify at least one of the param:begin and param:end -parameters. +== INITIALIZATION PARAMETERS -param:begin='BEGIN' (string or integer):: - Set the trimmer's beginning time to 'BEGIN'. +param:begin='TIME' vtype:[optional string or signed integer]:: + Set the trimming time range's beginning time to 'TIME'. + -If 'BEGIN' is a string, see <> for -its format. If 'BEGIN' is an integer, it is the number of nanoseconds -since Epoch. +If 'TIME' is a string, see below for its format. If 'TIME' is a signed +integer, the component converts it to a string and treats it as such. + If you don't specify this parameter, the component discards no events -until the end of the trimming range. - -param:clock-gmt=`yes` (boolean):: - Set the time zone of the param:begin and param:end parameters - to GMT instead of the local time zone. +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 +first upstream message's time to determine the date. -param:end='END' (string or integer):: - Set the trimmer's end time to 'END'. +param:end='TIME' vtype:[optional string or signed integer]:: + Set the trimming time range's end time to 'TIME'. + -If 'END' is a string, see <> for -its format. If 'END' is an integer, it is the number of nanoseconds -since Epoch. +If 'TIME' is a string, see the param:begin parameter for its format. If +'TIME' is a signed integer, the component converts it to a string and +treats it as such. + If you don't specify this parameter, the component discards no events -from the beginning of the trimming range. +from the beginning of the trimming time range. +param:gmt=`yes` vtype:[optional boolean]:: + Set the time zone of the param:begin and param:end parameters + to GMT instead of the local time zone. -PORTS ------ -Input -~~~~~ -`in`:: - Single input port from which the component receives the - notifications. +== PORTS + +---- ++-------------------+ +| flt.utils.trimmer | +| | +@ in out @ ++-------------------+ +---- -Output -~~~~~~ -`out`:: - Single output port to which the components sends the notifications - of which the time is in the trimming range. +=== Input -QUERY OBJECTS -------------- -This component class has no objects to query. +`in`:: + Single input port. -ENVIRONMENT VARIABLES ---------------------- -include::common-common-compat-env.txt[] +=== Output -`BABELTRACE_FLT_UTILS_TRIMMER_LOG_LEVEL`:: - Component class's log level. The available values are the - same as for the manopt:babeltrace2(1):--log-level option of - man:babeltrace2(1). +`out`:: + Single output port. include::common-footer.txt[] -SEE ALSO --------- -man:babeltrace2-plugin-utils(7), -man:babeltrace2-intro(7) +== SEE ALSO + +man:babeltrace2-intro(7), +man:babeltrace2-plugin-utils(7)