Flow Datasource

You can use the Flow datasource to retrieve application- and conversation-related metrics derived from OpenNMS flows data. The query editor supports the following functions:

Function Description

Combine functions

topN

Limit the results to the top N conversations or applications when sorted by total bytes.

includeOther

Combine and include other conversations or applications that fall outside of the top N.

Filter functions

withExporterNode

Filter for flows related to the given exporter node.

withIfIndex

Filter for flows related to the given interface index.

withDscp

Filter for flows with the given DSCP values.

withApplication

Filter for flows with the given application values. Do not use with topN.

withConversation

Filter for flows with the given conversation values. Do not use with topN.

withHost

Filter for flows with the given host values. Do not use with topN.

Transform functions

toBits

Convert the values from bytes to bits.

perSecond

Convert the values to a per-second rate.

negativeEgress

Make egress values negative.

negativeIngress

Make ingress values negative.

asTableSummary

Generate a tabular summary instead of time series data.

combineIngressEgress

Combine ingress and egress values.

onlyIngress

Display only ingress traffic.

onlyEgress

Display only egress traffic.

withGroupByInterval

Changes the resolution of the returned datapoints grouping by the given time interval (10s, 5m, 1h, and so on).

withPrefix

Specifies a prefix for graph and summary labels.

withSuffix

Specifies a suffix for graph and summary labels.

nanToZero

Convert all NaN values to zero (0) so that reduce expressions (sum, max) can take them into consideration.

Template queries

locations()

The locations() query returns a list of available node locations. You can create a variable with a locations() query and use that variable inside an exporterNodesWithFlows() query to filter the number of nodes displayed by location.

Example expressions
exporterNodesWithFlows(location='Default')
nodeFilter(location='$location') (1)
1 Assumes that the $location variable is populated with a value from a locations() query.

exporterNodesWithFlows(<filterQuery>)

The exporterNodesWithFlows() query returns a list of nodes that have exported flows data to OpenNMS. The template value is the node’s ID, and the display text is the node’s label.

The specified exporters must be part of your OpenNMS instance’s inventory to be returned by this query.

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

Example expressions using exporterNodesWithFlows()
exporterNodesWithFlows(<node_attribute>='<value>')
exporterNodesWithFlows(location='Default')
exporterNodesWithFlows(location='$location')
exporterNodesWithFlows(location='$location' & label='localhost')
exporterNodesWithFlows(location='$location' & label='.*com.*')

For more information about filters, see Filters in the main OpenNMS documentation.

interfacesOnExporterNodeWithFlows(<nodeCriteria>)

The interfacesOnExporterNodeWithFlows() query returns a list of interface indexes that are associated with one or more flows on a specified node. The value of the template variable is the interface’s index, and the display text is the interface’s name.

Only one argument is available for the interfacesOnExporterNodeWithFlows() query:

Argument Description

nodeCriteria

Criteria (node ID, or node foreign source and node foreign ID) of the node on which to enumerate interfaces.
Example expressions using interfacesOnExporterNodeWithFlows()
interfacesOnExporterNodeWithFlows($node) (1)
interfacesOnExporterNodeWithFlows(123) (2)
interfacesOnExporterNodeWithFlows(FS:FID) (2)
1 Assumes that the $node variable is populated with a value from an exporterNodesWithFlows() query.
2 Queries specific nodes using their IDs or foreignSource:foreignId tuples.

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

The dscpOnExporterNodeAndInterface() query returns a list of DSCP values that are used by one or more flows on the specified node and interface during the given time range. It returns selection options for the DSCP values, and IP precedence groups that cover them. Their labels are symbolic names for the DSCP codes, followed by the corresponding number (if applicable).

The following arguments are available for the dscpOnExporterNodeAndInterface() query:

Argument Description

nodeCriteria

Criteria (node ID, or node foreign source and node foreign ID) of the node on which to enumerate values.

interface

Interface index of the SNMP interface to enumerate.

from

Beginning of the time range for which to return values, in epoch milliseconds.

to

End of the time range for which to return values, in epoch milliseconds.
Example expression using dscpOnExporterNodeAndInterface()
dscpOnExporterNodeAndInterface($node, $interface, $__from, $__to) (1)
1 Assumes that the $node variable is populated with a value from an exporterNodesWithFlows() query, and the $interface variable is populated with a value from the interfacesOnExporterNodeWithFlows($node) query.

applications(<limit>)

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

The query accepts an optional number of records, which ensures that only a limited number of records is retrieved.

The application values retrieved come "as is" from the flows/applications/enumerate API.
Example expressions
applications(1000)
withApplications($applications) (1)
1 Assumes that the $applications variable is populated with a value from an applications() query.

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

The conversations() query returns a list of all available conversations. This query is intended for use inside the withConversation() filter function as a template variable, if necessary.

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

The query accepts the following optional arguments:

Argument Description Position Default Value

application

Application expression

1

.*

location

Location expression

2

.*

protocol

Protocol expression

3

.*

limit

Limit for the number of records retrieved.

Last

25
Example expressions
conversations(10) (1)
conversations(app0, 10) (2)
conversations(app0, Default, 10) (3)
conversations(app.*, Def.*, http.*, 1000) (4)
withConversation($conversations) (5)
1 Queries all conversations and returns a maximum of 10 records.
2 Queries all conversations in the app0 application and the default location, and returns a maximum of 10 records.
3 Queries all conversations using the http protocol in the app0 application and the default location. Returns a maximum of 10 records.
4 Queries all conversations using the http and https protocols in applications starting with app, in locations starting with Def. Returns a maximum of 1,000 records.
5 Assumes that the $conversations variable is populated with a value from a conversations() query.

hosts(<pattern>,<limit>)

The hosts() query returns a list of available hosts. This query is intended for use inside the withHost() filter function as a template variable, if necessary.

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

This query accepts the following optional arguments:

Argument Description Position Default Value

pattern

Host expression

1

.*

limit

Limit for the number of records retrieved.

Last

25
Example expressions
hosts(10) (1)
hosts(192.168.0.*, 10) (2)
withHost($hosts) (3)
1 Queries all hosts and returns a maximum of 10 records.
2 Queries all hosts matching the 192.168.0.* pattern and returns a maximum of 10 records.
3 Assumes that the $hosts variable is populated with a value from a hosts() query.