Performance Datasource

You can use the Performance datasource to retrieve performance metrics (for example, data collection and response time metrics) from the OpenNMS Measurements API. For an example of the Performance datasource in use, see Use variables to create dynamic dashboards.

Query editor

This section lists the types of queries that you can build using the query editor.

Attribute queries

Attribute queries are used to extract data points from the time series data that OpenNMS collects and stores. You can specify which attributes or series to query.

Attribute query options
Field Name	Description	Allowed Filter Expressions
Node	The node ID or `FS:FID` (foreign source and foreign ID tuple) of the node to query. Can also be a variable with a `nodeFilter()` query.	None
Resource ¹	The resource ID that contains 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. Can be used to query metrics which are modeled using many datasources in a single RRD file (for example, `StrafePing`).	None
Fallback Attribute	Name of the attribute to query if the requested attribute is not available.	None
Aggregation	RRD aggregation to use when exporting metrics (`Average`, `Min`, `Max`, `Last`). Defaults to `Average`.	None
Label	Name for the series. Must be unique for all attributes and expression results in the query.	None

The Resource and Attribute fields allow the * (match any text) and | (match the expression to the left or right of the character) filter characters. With them, you can create search patterns that let you retrieve multiple resources and attributes using a single query.

Given the following resources, the table below shows an example of possible filter expressions:

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

Example filter expressions
Filter 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

String property queries are used to read the last value of string-valued properties that OpenNMS collects and stores. You can specify which string property to query.

A panel can contain multiple string property queries, and their results can be visualized in a table. You can use Grafana’s transforms ("Filter by Name," "Organize Fields," or "Merge") to adjust the tables as desired.

String property query options
Field Name	Description
Node	ID of the node to query. Can also be a variable with a `nodeFilter()` query.
Resource	The resource ID that contains the requested attribute. Can also be a variable with a `nodeResources()` query.
String Property	Name of the attribute to query.

Expression queries

Expression queries are used to combine or otherwise transform one or more series into a new series. They support the mathematical and conditional operators that JEXL provides. Expression queries are sent over the OpenNMS Measurements API to be processed server-side (see More advanced expressions in the main OpenNMS documentation).

Expression query options
Field Name	Description
Expression	JEXL expression
Label	Name for the series resulting from the expression.

Filter queries

Filter queries are used to create new series, or alter existing ones. The options provided depend on the filter that you select.

Filter query options
Filter Name	Description
Chomp	Strips leading and trailing rows that contain nothing but `NaN` or `null` values.
HoltWinters	Performs Holt-Winters forecasting.
Outlier	Removes outliers and replaces them with interpolated values.
Trend	Fits a trend line or polynomial to a given column.
JEXL	Generic JEXL expression filter.
Percentile	Calculates percentiles.
Derivative	Calculates the derivative (rate of change) between rows.

Variable queries

You can use variable queries in metric queries and panel titles. The results will appear as a drop-down list at the top of the dashboard; you can select from the list to change the data that the associated panel displays. For an example of a variable query, see Use variables to create dynamic dashboards.

locations()

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

Example locations() expressions using nodeFilter()

nodeFilter(location='Default')
nodeFilter(location='$location') (1)

1	This example assumes you have a `location` variable with a `locations()` query.

nodeFilter(<filterQuery>[,labelFormat[,valueFormat]])

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

Example expressions using nodeFilter()

nodeFilter(catincProduction & catincLinux) (1)
nodeFilter(location='Default' & catincProduction & catincSNMP) (2)
nodeFilter() (3)
nodeFilter(labelFormat=id:label,valueFormat=id) (4)

1	Returns the set of nodes that are in the `Production` and `Linux` categories.
2	Returns the set of nodes that are in the `SNMP` and `Production` categories and the `Default` location.
3	Returns all nodes in inventory.
4	Returns all nodes in inventory, with label and value formatting applied.

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

Argument	Description
filterQuery	Any valid node query syntax as used by core OpenNMS services (see Filters in the main OpenNMS documentation). If omitted, all nodes are returned.

Argument

Description

filterQuery

Any valid node query syntax as used by core OpenNMS services (see Filters in the main OpenNMS documentation). If omitted, all nodes are returned.

labelFormat and valueFormat attributes can be specified. Please refer to the Entity Datasource documentation for more information on these options. By default, Performance Datasource variables default the labelFormat to label and the value to fs:fid if the node is part of a requisition, otherwise the value will be the node id.

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

The nodeResources() query returns a list of resource IDs that are available on the specified node. An optional second argument specifies whether to display the resource’s ID, its label, or its name in the template value selector and elsewhere. By default, the query displays the resource’s ID. An optional third argument specifies an exact resource-type name (for example, interfaceSnmp). Passing a wildcard (*) allows for resources of all types to be returned.

You can use regular expressions in the variable query to filter which resource IDs are used.

Examples of nodeResources() queries

nodeResources(123) (1)
nodeResources(FS:FID) (2)
nodeResources(42, label, interfaceSnmp) (3)
nodeResources(42, label, *, .*DPN.*) (4)
nodeResources($node) (5)

1	Queries a specific node by its ID (`123`).
2	Queries a specific node by its foreign source and foreign ID, formatted as a tuple.
3	Queries node ID `42` for only SNMP interface resources. The result displays the interface’s resource labels rather than their IDs.
4	Queries node ID `42` for all resources and returns items whose labels match the regular expression `.DPN.`.
5	Queries for all resources on the node returned from a `nodeFilter()` query. When requesting resources from a node based on another variable, the node variable should return only a single node.

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

Argument Description Default Value

Argument	Description	Default Value
Required
nodeId	The node (identified either by its `databaseId` or `foreignSource:foreignId` tuple) to display resources from.	Blank
Optional
textProperty	Sets alternate string values (`id`, `label`, or `name`) in the variable drop-down list.	id
resourceType	Filter to limit the types of resources returned by the query.	`*`
regexFilter	Regular expression filter applied to the value of the field specified by `textProperty`.	`.*`

Required

nodeId

The node (identified either by its databaseId or foreignSource:foreignId tuple) to display resources from.

Blank

Optional

textProperty

Sets alternate string values (id, label, or name) in the variable drop-down list.

resourceType

Filter to limit the types of resources returned by the query.

*

regexFilter

Regular expression filter applied to the value of the field specified by textProperty.

.*

Label formatters

The plugin provides a number of formatting functions that you can use to transform the labels displayed in graph legends. You can use one or more of them to transform the labels based on node or resource metadata returned from OpenNMS (requires Horizon 24 or newer).

nodeToLabel(<nodeCriteria>)

The nodeToLabel() function replaces the specified node’s ID with its label. You can specify either a node ID or a foreignSource:foreignId tuple. You can also use a template variable based on a custom list of node identifiers, or the results of a nodeFilter() query.

Examples of nodeToLabel() functions

nodeToLabel($node) (1)
nodeToLabel(123) (2)
nodeToLabel(FS:FID) (2)

1	Queries a template variable that represents a list of node identifiers.
2	Queries specific nodes using their IDs or `foreignSource:foreignId` tuples.

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

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

The single-argument form of this function expects a complete resource ID. That resource ID must be the full resource identifier as queried to the OpenNMS Measurements API. The two-argument form of this function lets you use template variables to specify a node and separately provide the remainder of the resource ID that you want to translate.

A partial resource ID is the portion of the resource identifier that does not identify the node itself (for example, nodeSnmp[], responseTime[127.0.0.1]). For example, all of these calls translate into the same text:

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

1	Assumes that the `$node` variable is populated with a value from a `nodeFilter()` query, and the `$interface` variable is populated with a value from a `nodeResources()` query.

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

The resourceToName() function behaves similarly to resourceToLabel(), but it returns the resource’s name rather than its label. The resource name is usually the resource’s internal, machine-readable name (for example, a node criteria or an interface name and MAC address).

Examples of resourceToName() functions

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

1	Assumes that the `$node` variable is populated with a value from a `nodeFilter()` query, and the `$interface` variable is populated with a value from a `nodeResources()` query.

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

The resourceToInterface() function transforms a resource ID, or a combination of node criteria and a partial resource ID, into another value. It is a special case of the other, more general methods; it takes the label of the resource (assumed to be an interface-MAC formatted string) and returns the interface portion of the label.

Datasource configuration options

Enable Input Value Override Components

When configuring a Performance Query, you provide values for types, nodes, resources, attributes, etc. Generally these are dropdown inputs with specific values, and may include template variables. In some cases, the dropdowns have validation that will only accept the displayed predefined values or text entered in a particular format. In these cases, it may be necessary or desirable to bypass these restrictions and enter a free-form text value or expression.

If "Enable Input Override Components" is enabled in the Performance Datasource configuration page, then some inputs will display a switch, which if enabled will display a text input box to allow you to manually enter any text for that value.

This is disabled by default as it is generally not needed.