Metadata

Horizon supports the assignment of arbitrary metadata to nodes, interfaces and services. You can then use this metadata to dynamically configure service monitoring, performance data collection, service detection, and expression-based thresholds.

The metadata is a simple triad of strings containing a context, a key and the associated value. Each node, each interface and each service can have an arbitrary number of metadata elements assigned to it. The only restriction is that the tuple of context and key must be unique in the element with which it is associated.

The association of metadata with nodes, interfaces, and services happens during provisioning with the use of detectors. Users can add, query, modify, or delete metadata through the requisition editor in the web UI, or through the ReST endpoints.

A simple domain-specific language (DSL) lets users access the metadata associated with the elements they are working on, and use it as a variable in parameters and expressions. There is no limitation in defining metadata: users can decide how to define it and use it in expressions.

View metadata currently assigned to nodes, interfaces and services, on the details page associated with that entity in the web UI:

metadata view

Contexts

A context distinguishes different kinds of metadata use. Horizon uses several default contexts: pattern (used with polling), requisition, node, interface, and service.

Three special contexts provide details about nodes, interfaces and services objects. Each context has keys associated with it that you can use in a metadata expression.

You can create user-defined contexts in the ReST API by prefixing the context name with X-. Using an X- prefix can help to avoid future Horizon contexts interfering with a user-defined context, since Horizon contexts are not prefixed in this way.

Node context

The node context provides details about the node currently processed. The following keys are available under this context:

Context:Key Description

node:label

The node’s label

node:foreign-source

The node’s foreign source name

node:foreign-id

The node’s foreign ID

node:netbios-domain

The NetBIOS domain as provided by SNMP

node:netbios-name

The NetBIOS name as provided by SNMP

node:os

The node’s operating system

node:sys-name

The system name of the node

node:sys-location

The system location of the node

node:sys-contact

The system contact specified for the node

node:sys-description

The system description of the node

node:location

The node’s monitoring location name

node:area

The node’s monitoring location area

node:geohash

A Geohash of the node’s latitude/longitude

Interface context

The interface context provides details about the interface currently processed. The following keys are available under this context:

Context:Key Description

interface:hostname

The hostname associated with the IP address of the interface

interface:address

The IP address of the interface

interface:netmask

The netmask of the interface

interface:if-index

The SNMP interface index

interface:if-alias

The SNMP interface alias

interface:if-description

The SNMP interface description

interface:phy-addr

The physical address of the interface

Service context

The service context provides details about the service currently processed. The following key is available under this context:

Context:Key Description

service:name

The full name of the service

SCV (Secure Credentials Vault)

The special context scv provides access to values stored in the Secure Credentials Vault. The key used in this context must consist of the alias and the attribute of the credential separated by a colon.

Example: ${scv:mydevice:password}. This will access the password attribute of a credential named mydevice.

Adding Metadata through the Web UI

You can edit the requisition context in the web UI:

  1. Under the admin menu, select Configure OpenNMS.

  2. Select Manage Provisioning Requisitions.

  3. Click the edit icon beside the requisition you want to work with.

  4. Click edit beside the node you want to work with.

  5. In the Meta-Data area, click Add Meta-Data.

    metadata add

  6. Specify node or interface as the scope of where the metadata will apply.

  7. Specify the key and a value and click Save.

The Metadata DSL

The metadata DSL lets you interpolate metadata into a parameter. The syntax lets you use patterns like ${context:key|context_fallback:key_fallback|…​|default} in an expression.

Each expression can contain multiple references to metadata that will be replaced with the corresponding value during evaluation. Placeholders start with ${ and end with } containing a reference to a context-key pair. You may choose to define multiple fallback context-key pairs and and an optional trailing default value. Separate context and key by a :. Use a | to separate optional fallback context-key pairs and default value. If the first context:key item is not available (not on a service, interface, node or any other of the special contexts) the next one after the | is used. The last one, the default value, is not interpreted as a context:key but is used as a literal and will always succeed.

The interpolation supports recursive evaluation. This allows a user to specify an pattern inside another pattern or to provide whole expressions stored as metadata.

Examples

${requisition:username}

Will resolve to the username as defined in the requisitioning UI or an empty value, if there is no such username defined.

A placeholder can contain an optional default value which is separated by a |.

${requisition:username|admin}

Will resolve to the username as defined in the requisitioning UI or to the value admin, if there is no such username defined.

Use fallback context-key pairs in a placeholder after the primary context-key pair to specify other values if the primary context-key pair is not defined. Separate each fallback context-key-pair by a |.

${requisition:username|requisition:account|admin}

Will resolve to the username as defined in the requisitioning UI. If there is no such username defined, the fallback account will be used. If neither exist, the fallback value admin will be used.

${scv:${requisition:credentials|node:label}:password} Will resolve the credentials value specified in the requisition UI while using the node label as fallback value. This in turn is used to resolve the outer pattern and access the final password for this device.

To resolve the value associated with context-key pair, the DSL uses scopes that determine the resolution order. The last scope will be queried first and if a scope does not contain the queried context-key tuple, the next one will be queried. For example, the resolution of a query on a service entity would be service metadata→interface metatdata→node metadata. On an interface, it is metadata→interface metatdata→node metadata. On the node level, only the node is queried.

Which scopes are available depends on the environment for which an expression is evaluated and is documented in the corresponding places elsewhere in this guide. Some environments also provide additional scopes that are not backed by the persisted metadata but provide additional metadata related to the current evaluation.

Testing an expression

To test an expression, there is a karaf shell command which interpolates a string containing a pattern to the final result:

admin@opennms> opennms:metadata-test -n 1 -i 192.168.0.100 -s ICMP '${fruits:apple|fruits:banana|vegetables:tomato|blue}'
---
Meta-Data for node (id=1)
fruits:
  apple='green'
  banana='yellow'
vegetables:
  tomato='red'
---
Meta-Data for interface (ipAddress=192.168.0.100):
fruits:
  apple='brown'
---
Meta-Data for service (name=ICMP):
fruits:
  apple='red'
---
Input: '${fruits:apple|fruits:banana|vegetables:tomato|blue}'
Output: 'red'
Details:
  Part: '${fruits:apple|fruits:banana|vegetables:tomato|blue}' => match='fruits:apple', value='red', scope='SERVICE'
admin@opennms>

Uses

The following places allow the use the Metadata DSL: