Performance datasource

General

Use the Performance Datasource to retrieve performance metrics (i.e., data collection and/or response time metrics) from the Measurements API in OpenNMS.

(For an example of the performance datasource in action, see Using Template Variables to Create Dynamic Dashboards).

The query editor provides the ability to build queries of the following types:

Attribute queries

Used to extract data points from time series data that OpenNMS collects and stores. The query is used to identify which attribute(s) (or series) are being queried.

Name Description Allowed Filter Expressions

Node

Node ID, or FS:FID (foreign source and foreign id) of the node to query. Can also be a variable with a nodeFilter() query.

Resource

Resource ID containing the requested attribute. Can also be a variable with a nodeResources() query.

* , |

Attribute

Name of the attribute to query.

* , |

Sub-Attribute

Name of the sub-attribute to query. This can be used to query metrics which are modeled using many datasources in a single RRD file (i.e., StrafePing).

Fallback Attribute

Name of the attribute to query if the requested attribute was not available.

Aggregation

RRD aggregation to use when exporting the metrics. Possible values are Average, Min, Max, or Last. Defaults to Average.

Label

Name for the series. Must be unique for all attributes and expression results in the query.

Resource and Attribute fields allow * and | filter characters to create search patterns that allow you to retrieve multiple resources and attributes in a single query.

  • * : match any text

  • | : match the expression on the left OR right side of the pipe (|)

Examples:

Given the following list of resources, the table below shows an example of filter expressions.

  • interfaceSnmp[eth0-00e08177b841]

  • interfaceSnmp[Default-0001d7709c83]

  • interfaceSnmp[HR_VLAN-0001d7709c87]

  • interfaceSnmp[Facilities_VLAN-0001d7709c85]

Expression Result

interfaceSnmp[*]

interfaceSnmp[eth0-00e08177b841], interfaceSnmp[Default-0001d7709c83], interfaceSnmp[HR_VLAN-0001d7709c87], interfaceSnmp[Facilities_VLAN-0001d7709c85]

interfaceSnmp[*VLAN*]

interfaceSnmp[HR_VLAN-0001d7709c87], interfaceSnmp[Facilities_VLAN-0001d7709c85]

interfaceSnmp[Facilities*|Default*]

interfaceSnmp[Facilities_VLAN-0001d7709c85], interfaceSnmp[Default-0001d7709c83]

String property queries

Used to read the last value of string-valued properties that OpenNMS collects and stores. The query identifies which string property is queried. A panel can contain multiple string property queries. The result can be visualized in a table. Use Grafana’s transforms like "Filter by name", "Organize Fields", or "Merge" to adjust the visualized table as needed.

Name Description

Node

Node ID of the node to query. Can also be a variable with a nodeFilter() query.

Resource

Resource ID containing the requested attribute. Can also be a variable with a nodeResources() query.

String Property

Name of the attribute to query.

Expression queries

Used to combine or otherwise transform one or more series into a new series. Supports mathematical and conditional operators provided by JEXL. Consult the Measurements API documentation of your OpenNMS version for more details.

Name Description

Expression

JEXL expression

Label

Name for the series resulting from the expression.

Filter queries

Used to create new and/or alter existing series.

The option provided depend on the selected filter.

Outlier filter

Used to remove datapoints from the series that fall outside of the configured quantile, defaults to 95%. The datapoints are replaced with interpolated values.

Template queries

Use template queries in metric queries and panel titles. The results will appear as a drop-down list at the top of the dashboard. You can then select from the list to change the data the panel displays. See Using Template Variables to Create Dynamic Dashboards for an example.

locations()

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

Example variable expression
  • nodeFilter(location='Default')

  • nodeFilter(location='$location')

nodeFilter(<filterQuery>)

The nodeFilter() query returns a list of nodes which match the given filter expression.

For example, to return the set of nodes that are in the Production and Linux categories, or to return the set of nodes that are in the SNMP and Production categories and Default location you can use:
  • nodeFilter(catincProduction & catincLinux)

  • nodeFilter(location='Default' & catincProduction & catincSNMP)

The available arguments are as follows:

Name Description

filterQuery

Any valid node query syntax as used by core OpenNMS services.

nodeResources(<resourceId>[,textProperty[,resourceType[,regexFilter]]])

The nodeResources() query will return the list of resource IDs which are available on the given node. An optional second argument specifies whether to show the resource’s ID (the default), label, or name in the template value chooser and elsewhere. An optional third argument specifies an exact resource-type name (e.g. interfaceSnmp); a value of * makes explicit the default behavior of returning resources of all types. Regular expressions in the template query can then be used to filter which resource IDs are used.

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

nodeResources(123)

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

nodeResources(FS:FID)

To query only SNMP interface resources on the node with ID 42, and to display the interface’s resource labels rather than their often-cryptic IDs, you might use:

nodeResources(42, label, interfaceSnmp)

To query all resources on the node with ID 42, and labels that match the regular expression *.DPN.*, you might use:

nodeResources(42, label, *, .*DPN.*)

The available arguments are as follows:

Name

Required

Default

Description

resourceId

Required

(none)

The ID of the node (either databaseId or foreignSource:foreignId) for which to display resources.

textProperty

Optional

id

One of id, label, or name to display alternate string values in the variable drop-down menu.

resourceType

Optional

*

Resource type filter to limit the types of resources returned.

regexFilter

Optional

.*

Regular expression filter applied to the resource field specified by the textProperty argument. This filter is applied to the value of the selected textProperty field.

Label formatters

Helm provides a number of formatting functions you can use to transform the labels shown in graph legends.

You can use one or more of these to transform the displayed labels based on node or resource metadata returned from OpenNMS Horizon 24 or above.

nodeToLabel(<nodeCriteria>)

The nodeToLabel() function will be replaced with the label of the node specified.

You can pass either a node ID or foreign-source:foreign-id tuple. It is also possible to use a template variable based on a custom list of node identifiers or the results of a nodeFilter() query.

To use a template variable representing nodes, just pass it, like so:

nodeToLabel($node)

To manually specify by ID or node criteria, just pass them in raw:

nodeToLabel(123)
nodeToLabel(FS:FID)

resourceToLabel(<resourceId or nodeCriteria>[, <partialResourceId>])

The resourceToLabel() function converts an OpenNMS resource identifier or node criteria and partial identifier into the resource’s label. The format of the resource label depends on the resource, and can be anything from a node label, to a descriptive string for an IP interface.

The 1-argument form of this call expects a complete resource ID. That resource ID must be the full resource identifier as queried to the measurements API.

The 2-argument form of this call lets you use template variables to choose a node and then separately provide the remainder of the resource ID you want to translate.

A partial resource ID is just the portion of the resource identifier that doesn’t identify the node itself, like nodeSnmp[] or responseTime[127.0.0.1].

For example, both of these resourceToLabel calls would be translated into the same text:

resourceToLabel(node[FS:FID].nodeSnmp[])
resourceToLabel(FS:FID, nodeSnmp[])

resourceToName(<resourceId or nodeCriteria>[, <partialResourceId>])

The resourceToName() function behaves exactly like the resourceToLabel() function, only it returns the resource’s name, rather than its label. The resource name is usually the internal, machine-readable name of the resource, like a node criteria, or an interface name + MAC address.

resourceToName(node[FS:FID].nodeSnmp[])
resourceToName(FS:FID, nodeSnmp[])

resourceToInterface(<resourceId or nodeCriteria>[, <partialResourceId>])

Finally, just like resourceToLabel() and resourceToName(), resourceToInterface() transforms a resource ID or combination node criteria and partial resource ID into another value.

It is a special case of the other more general methods that will take the label of the resource (assumed to be an interface-MAC formatted string) and just return the interface portion.