The Filter filter function provides a mechanism for creating subsets of Telemetry streams in a variety of ways.
Filter determines the subset to be returned in a two stage process. In the first stage, it creates a ranked sequence of the passed telemetry Streams according to a criteria specified by a parameter. For example, the first stage could order telemetry streams by determining the maximum valued data point in each individual stream, and then sorting the streams by order of these values. Another example would be to order them by the average value appearing in each individual stream.
Once an ordering has been imposed on the telemetry streams, the second stage applies a filter to produce the subset of streams to be returned. For example, the second stage could specify that only the "top 10" streams (according to their sorted order) should be returned. Another example would be the "bottom 20 percent".
As indicated below, the Filter filter function provides four parameters: the first specifies the set of streams to be filtered, the second specifies the criteria to be used for sorting in the first stage, and the remaining two parameters specify the filtering to be applied in the second stage.
Table 27.1.
| Parameter | Description |
|---|---|
| Streams | A stream expression |
| SortCriteria | A string indicating the sorting criteria to be applied to Streams. Acceptable String values and their meanings are: (1) "Avg", which sorts the telemetry streams according to the average value of their data points; (2) "Max", which sorts the telemetry streams according to the maximum value in their data points; (3) "Min", which sorts the telemetry streams according to the minimum value in their data points, (4) "Last", which sorts the telemetry streams according to the last value appearing in their data points; (5) "Delta", which sorts the telemetry streams according to the sum of the absolute value change between two consecutive data points; and (2) "SimpleDelta", which sorts the telemetry streams according to the difference between the last entry and the first entry in their data points. |
| ThresholdCriteria | A string indicating the threshold used to separating those streams that should be returned and those that should be filtered out. Most thresholds require an integer ThreshholdValue, which would be provided as the parameter following this one. Acceptable ThresholdCriteria and their meanings include: (1) "Above", meaning only those telemetry streams whose sort value is above ThresholdValue are returned; (2) "Below", meaning only those telemetry streams whose sort value is below ThresholdValue are returned; (3) "Top", meaning only the top ThresholdValue telemetry streams in sorted order are returned; (4) "Bottom", meaning only the bottom ThresholdValue telemetry streams in sorted order are returned; (5) "TopPercent", meaning only the top ThresholdValue percent of the telemetry streams in sorted order are returned; (5) "BottomPercent", meaning only the bottom ThresholdValue percent of the telemetry streams in sorted order are returned; |
| ThresholdValue | An integer indicating the value to be used with the ThresholdCriteria. When the ThresholdCriteria is "TopPercent" or "BottomPercent", then the ThresholdValue must be between 0 and 100. |
The following streams definition shows the use of the Filter filter function to return the three coverage streams whose percentage has decreased the most.
streams TopLevelWorkspaceCoverageStreams() = {
"Filtered workspace coverage",
Filter(FilterZero(WorkspaceCoverage("Percentage", "**", "line")), "SimpleDelta", "Bottom", 3)
};
This definition begins by calling the WorkspaceCoverage reduction function to generate the coverage associated with all top-level modules. As we've seen in Section 5.8, “Managing Chart and Report complexity with Filter Functions”, the use of this reduction function on a Project with a large number of modules tends to produce an unusable Chart. Let's assume that what we would really like to know is what modules are changing in a negative way with respect to their Coverage--in other words, the drop in percentage coverage from the beginning of the time period to the end is greatest. To obtain that chart, we first wrap the WorkspaceCoverage reduction function invocation with the FilterZero filter function. This eliminates the modules reporting zero coverage throughout the time interval. We pass the remaining non-zero streams to Filter, indicating that we want to order them using the "SimpleDelta" sort criteria, and then filter out all but the bottom three (i.e. the most negative change). That would give us a chart with the biggest losers, coverage-wise.