Flow datasource

General

Use the Flow Datasource to retrieve application- and conversation-related metrics derived from flow data stored by OpenNMS.

The query editor supports the following functions:

Category Name Description

Combine

topN

Limit the results to the Top N conversations/applications when sorted by total bytes.

Combine

includeOther

Combine and include other conversations/applications that fall outside of the Top N.

Filter

withExporterNode

Filter for flows related to the given exporter node.

Filter

withIfIndex

Filter for flows related to the given interface index.

Filter

withDscp

Filter for flows with the given DSCP value(s).

Filter

withApplication

Filter for flows with the given application value(s). Use without topN.

Filter

withConversation

Filter for flows with the given conversation value(s). Use without topN.

Filter

withHost

Filter for flows with the given host value(s). Use without topN.

Transform

toBits

Convert the values from bytes to bits.

Transform

perSecond

Convert the values to a per/second rate.

Transform

negativeEgress

Make the egress values negative.

Transform

negativeIngress

Make the ingress values negative.

Transform

asTableSummary

Generate a tabular summary instead of time series data.

Transform

combineIngressEgress

Sum ingress and egress values together.

Transform

onlyIngress

Only display ingress traffic.

Transform

onlyEgress

Only display egress traffic.

Transform

withGroupByInterval

Changes the resolution of the returned datapoints grouping by the given time interval (in the format of: 10s, 5m, 1h, etc.).

Transform

withPrefix

Specifies a prefix for graph and summary labels.

Transform

withSuffix

Specifies a suffix for graph and summary labels.

Transform

nanToZero

Convert all NaN values to zero (0) so they can be taken into consideration by reduce expressions like sum or max.

Template queries

locations()

The locations() query returns a list of all available node locations. Use this inside exporterNodesWithFlows() to filter the number of nodes displayed by location.

Example variable expression

  • exporterNodesWithFlows(location='Default')

  • exporterNodesWithFlows(location='$location')

exporterNodesWithFlows(<filterQuery>)

The exporterNodesWithFlows() query returns a list of nodes which have exported flow data to OpenNMS. The value of the template variable is the Node ID and the display text is the Node Label.

The exporters must be part of the node inventory in OpenNMS in order to be returned by this query.

For example, to query the exporters that have sent flows you can use the following expression:

exporterNodesWithFlows()

The filter expression must be an existing node attribute and its corresponding value. Separate multiple filter expressions with an '&' (<attribute1>=<value1> & <attribute2>=<value2> & …​). The value can be a constant, a variable, or a regular expression.

Example variable expression

  • exporterNodesWithFlows(<node_attribute>='<value>')

  • exporterNodesWithFlows(location='Default')

  • exporterNodesWithFlows(location='$location')

  • exporterNodesWithFlows(location='$location' & label='localhost')

  • exporterNodesWithFlows(location='$location' & label='.*com.*')

interfacesOnExporterNodeWithFlows(<nodeCriteria>)

The interfacesOnExporterNodeWithFlows() query returns a list of interface indexes which are associated with one or more flows on the given node. The value of the template variable is the Interface Index and the display text is the Interface Name.

The available arguments are as follows:

Name Default Description

nodeCriteria

(none)

Node criteria (Node ID, or Node Foreign Source and Node Foreign ID) of the node on which to enumerate the interfaces.

Assuming that the $node variable is populated with a value from the exporterNodesWithFlows query, you can use the following expression:

interfacesOnExporterNodeWithFlows($node)

To query a specific node by id, you can use an expression similar to:

interfacesOnExporterNodeWithFlows(123)

To query a specific node by foreign source and foreign id, you can use an expression similar to:

interfacesOnExporterNodeWithFlows(FS:FID)

dscpOnExporterNodeAndInterface(<nodeCriteria>,<interface>,<from>,<to>)

The dscpOnExporterNodeAndInterface() query will return a list of DSCP values which are used by one or more flows on the given node and interface and given time range. The query returns selection options for the found DSCP values and ip precedence groups that cover these values. Labels of selection options for DSCP codes are symbolic names for these DSCP codes followed by the corresponding number (if applicable).

The available arguments are as follows:

Name Default Description

nodeCriteria

(none)

Node criteria (Node ID, or Node Foreign Source and Node Foreign ID) of the node on which to enumerate.

interface

(none)

Interface Index of the SNMP interface to enumerate.

from

(none)

Start time in epoch milliseconds

to

(none)

End time in epoch milliseconds

Assuming that the $node variable is populated with a value from the exporterNodesWithFlows query and that the $interface variable is populated with a value from the interfacesOnExporterNodeWithFlows($node) query, you can use the following expression:

dscpOnExporterNodeAndInterface($node, $interface, $__from, $__to)

applications(<limit>)

The aplications() query returns a list of all available applications. This function is intended for use inside the Filter function withApplications() as a template variable if needed.

Currently this function accepts an optional number of records which ensures that only a limited number or records will be retreieved.

The application values retrieved come "as is" from the flows/applications/enumerate API.
Examples: variable expression

  • applications()

  • applications(1000)

Use with filter function withApplications()

  • withApplications($applications)

conversations(<application>,<location>,<protocol>,<limit>)

The conversations() query returns a list of all available conversations. This function is intended to be used inside the Filter function withConversation() as a template variable if needed. Currently this function accepts the following arguments:

Position Argument Description Default

1

application (optional)

application expression

".*"

2

location (optional)

location expression

".*"

3

protocol (optional)

protocol expression

".*"

last

limit (optional)

limit number of records retrieved.

25
Examples variable expression

Get all conversations (will return a maximum of 25 records).

  • conversations()

Get all conversations and return a maximum of 10 records.

  • conversations(10)

Get all conversations with application app0 and return a maximum of 10 records.

  • conversations(app0, 10)

Get all conversations with app0 under Default location and return a maximum of 10 records.

  • conversations(app0, Default, 10)

Get all conversations with app0 under Default location with http protocol and return a maximum of 10 records.

  • conversations(app0, Default, http, 10)

Get all conversations with application that start with app under location that start with Def and protocols http and https.

  • conversations(app.*, Def.\*, http.*, 1000)

Usage with filter function withConversation()

  • withConversation($conversations)

The conversations values retrieved come as is from flows/conversations/enumerate API.

hosts(<pattern>,<limit>)

The hosts() query returns a list of all available hosts. This function is intended to be used inside the Filter function withHost() as a template variable if needed. Currently this function accepts the following arguments:

Position Argument Description Default

1

pattern (optional)

host expression

".*"

last

limit (optional)

limit number of records retrieved

25
Examples: variable expression

Get all hosts (will return a maximum of 25 records).

  • hosts()

Get all hosts and return a maximum of 10 records.

  • hosts(10)

Get all hosts that match the pattern 192.168.0.* and return a maximum of 10 records.

  • hosts(192.168.0.*, 10)

Use with filter function withHost()

  • withHost($hosts)

The host values retrieved come "as is" from the flows/hosts/enumerate API.