keepOnlyMatchingLines (Compute)

When To Use

Use keepOnlyMatchingLines to filter a source table down to the rows you actually want to monitor: keep only the sensors of a given type, only the services whose name matches a connector variable, only the rows with a valid status. It is the table equivalent of grep: rows that do not match are discarded, rows that match pass through unchanged.

To do the opposite (discard matching rows), use excludeMatchingLines^[1]. To drop columns instead of rows, use keepColumns^[2].

Syntax

sources:
  temperatureSensors:
    type: commandLine
    commandLine: ${file::ipmi-sensors.sh}
    computes:
    - type: keepOnlyMatchingLines
      column: 1
      valueList: temperature

Properties

Provide regExp, valueList, or both. When both are specified, both are applied one after the other: a row is kept only if it matches the regExp and its value is in the valueList.

Table Transformation Example

With column: 1 and valueList: temperature:

Note that Temperature is kept: valueList comparison is case-insensitive.

Recommended Pattern

• Prefer valueList for exact category values (temperature, fan, enclosure); reserve regExp for real patterns.
• Filter as early as possible in the computes pipeline so subsequent computes process fewer rows.
• Drive regExp from a connector variable (regExp: ${var::serviceNames}) when the user should choose what to monitor, as done in LinuxService and WindowsProcess.
• Anchor the regex (^value$) when you need an exact match with regex features; otherwise abc also keeps xabcy.

Common Mistakes

• Forgetting that regExp is unanchored: regExp: 5 keeps every row whose column merely contains 5 — use valueList: 5 or regExp: ^5$ for an exact match.
• Expecting valueList to support patterns; it is a list of literal values only.
• Combining regExp and valueList and expecting an OR: the two criteria are ANDed.
• Counting columns from 0: column is 1-based.
• Writing Java-style alternation a|b where PSL-style a\|b is expected.

Community Examples

• IpmiTool^[3]
• WindowsProcess^[4]
• LinuxService^[5]

From IpmiTool:

  # Temperature;SensorID;SensorName;Location;Value;WarningThreshold;AlarmThreshold
- type: keepOnlyMatchingLines
  column: 1
  valueList: temperature