Entities Datasource

You can use the Entities datasource to retrieve entity model objects (alarms and nodes) from OpenNMS. For an example of the Entities datasource in use, see Create a Filter panel.

Datasource queries

This datasource’s behavior changes depending on the specified entity. Attributes and values also change based on the entity type.

The datasource allows only a single target. Subsequent targets in the query editor are ignored.

Template queries

You can pass a field name to the attribute variable to change the behavior of a template query. This changes the field’s display name. If no attribute argument is specified, the query returns the entity’s id attribute.

The query attribute’s default value is alarms(), meaning it returns a list of alarm IDs.

alarms([attribute])

The alarms() function queries the OpenNMS alarms REST API.

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 a nodeFilter() query to filter the number of nodes displayed by location.

Example expressions using nodeFilter()
nodeFilter(location='Default')
nodeFilter(location='$location')

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

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

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

labelFormat and valueFormat attributes can optionally be added to format the label (what is displayed with the variable selection dropdown boxes) and the value (the value that is used when referenced within Grafana). By default, Entity Datasource variables default to the node id for both of these values, however any of the following may be specified:

nodeFilter() label and value formats
Format Description

id

The node database id (a numeric value)

label

The node label

id:label

The node id and label

label:id

The node label and id

fs:fid

The node foreign source and foreign id

fs:label

The node foreign source and label
Example expressions using nodeFilter()
nodeFilter(<node_attribute>='<value>')
nodeFilter(location='$location' & label='localhost')
nodeFilter(labelFormat=label,valueFormat=id,location='$location')

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

nodes([attribute])

The nodes() query retrieves a list of unique values for a specified attribute from the OpenNMS node REST API. You can use its result in a nodeFilter() query to filter nodes either by entity or performance datasource. To find a list of valid attributes, see your OpenNMS server’s http://HOSTNAME:8980/opennms/api/v2/nodes/properties endpoint.

Follow these steps to filter nodes by a custom asset record:

  1. On your dashboard, create a variable named region.

  2. Set the variable’s datasource to an entity datasource that points to your server.

  3. Set the variable’s query to nodes(assetRecord.region).

  4. Click Save and return to the list of variables.

  5. Create a variable named node.

  6. Set the variable’s datasource to a performance datasource.

  7. Set the variable’s query to nodeFilter(region='$region').

  8. Click Save and return to your dashboard.

As you change the region variable, the options in the node variable should update to show only the matching nodes.