Telemetry filters

NAME

getfilter, setfilter, clearfilter - manipulate telemetry filters

SYNOPSIS

getfilter nodeHostname deviceID
setfilter nodeHostname -types type(s) -skip interval deviceID
clearfilter nodeHostname deviceID

NOTE: for these utilities, the service is specified as deviceID, not as port name.

DESCRIPTION

The getfilter, setfilter, and clearfilter utilities display and manipulate "telemetry filters" associated with a specified instrument service. When a telemetry retriever such as portal or getPackets requests packets from an instrument service, the service may decimate the number of packets returned through telemetry subsampling, i.e. by returning only every nth packet. The number of packets to skip for each packet type is specified by a "telemetry filter", and several such filters can be associated with an instrument service. The getfilter utility displays the telemetry filters currently associated with a specified instrument service; e.g. the following command displays the filters associated with instrument service 1101 running on the "surface" node:
% getfilter surface 1101
SIAM version $Name:  $
filter 0: types: SensorData : skip 3
filter 1: types: Metadata DeviceMessage Summary : skip 0
The displayed filters are applied sequentially by the service when telemetry is requested. In the above example, only every 4th sensor data packet will be retrieved by portal or getPackets (three sensor data packets are skipped), while every metadata, message, and summary packet will be retrieved. (Note that all packets are always logged by the service; the filters discussed here only apply to telemetry retrieval).

The clearfilter utility removes all telemetry filters from an instrument service.

The setfilter utility specifies one or more filters for an instrument service. Usage is as follows:
setfilter nodeHostname -types type(s) -skip interval deviceID
Valid types are 'metadata', 'data', 'message', 'summary', or 'all'. Valid skip interval should be specified as an integer. An interval of '0' means return all packets of the specified type(s), while an interval of '-1' means dont' return any packets of the specified type(s).

For example, the following commands clears all filters for instrument service 1101, then sets filtering to skip all sensor data and message packets from the service:
% clearfilter surface 1101
% setfilter -types data message -skip -1 1101
A subsequent invocation of getfilter shows:

% getfilter localhost 1101
SIAM version $Name:  $
filter 0: types: SensorData Metadata DeviceMessage Summary : skip 0
filter 1: types: SensorData DeviceMessage : skip -1

Note that the filters displayed by getfilter will be applied by the service sequentially. E.g. in the above example, "filter 0" passes all packets of all types, but "filter 1" will subsequently remove all sensor data and message packets.

KNOWN BUGS

There is currently no way to persist telemetry filters across service restarts, other than with the defaultSkipInterval property.

ENVIRONMENT

The following environment variables must be set:

JAVA_HOME - location of Java installation, e.g. /j9 or /opt/java/jdk1.3.1
JAVA - name of the JVM. E.g. on a Sidearm, JAVA should be set to j9. On a workstation with Sun's Java installed, JAVA could be set to java.
SIAM_HOME - top of the SIAM directory tree
SIAM_CLASSPATH - on a Sidearm, SIAM_CLASSPATH should be set to $JAVA_HOME/lib/jclMax/classes.zip:$JAVA_HOME/lib/prsnlmot.jar:$JAVA_HOME/lib/RXTXcomm.jar:$SIAM_HOME/classes. On X86 system, SIAM_CLASSPATH should be set to $SIAM_HOME/classes

SEE ALSO

Summaries and telemetry subsampling