How do object filters work?
Object filter components
An object filter is an XPath expression representing one or more network objects. The object filter indicates the objects to collect telemetry data from, such as an NE or a list of ports.
An XPath is composed of a series of XPath elements. Each element represents a step on the YANG model tree from left (root) to right (leaf or container). An element contains a name and a series of optional predicates.
Example: network-element[ne-id='10.1.0.0']
Predicates
A predicate is an expression within square brackets that identifies the instance of each XPath element. Keys and attributes of the object (as defined in the NSP model YANG) may be included.
Predicates can contain the following operators:
Subexpressions can be enclosed in parentheses to enforce order of operations.
Note: Comparison operators use string comparators, so “value2” is greater than “value11”.
Examples:
[ne-id='10.1.0.0' or ne-id='10.1.1.1']
[(type='7750 SR-12' and product='7750 SR') and (version='TiMOS-B 19.0.R1' or contains('version','15.0'))]
Predicate functions
The following functions are supported within a predicate:
-
contains('attribute', 'search-text')
searches for all objects where the named attribute contains the search text
-
containsIgnoreCase('attribute-name', 'search-text')
same as contains() but conducts a case-insensitive search
-
not(<binary-expression>|<function-expression>)
negates the result of the argument expression
-
A boolean function may be used to find objects by searching through an object’s children and references.
The boolean function returns true if at least one of the specified object references or children satisfies the condition.
If a boolean function includes an instance-identifier object, the following requirements apply:
Examples:
-
[contains('component-id','port=1') and not(contains('component-id','breakout'))]
-
To find endpoints on a specified service:
/nsp-service:services/service-layer/eline[service-id='service_epipe_12']/endpoint[boolean(service[nsp-model:schema-nodeid='/nsp-service:services/service-layer/eline'][name='service_epipe_12'])]
-
To find all ports with id 1/1/1/1 where mtu-value in the port-details has value 888:
/nsp-equipment:network/network-element/equipment/port[contains(component-id,'shelf=1/slot=1/card=1/port=1') and boolean(port-details[mtu-value = 888])]
In this example, the boolean function returns true only if an mtu-value of 888 is found in the port details.
-
To find the NEs associated with a specified controller:
/nsp-ne-control:ne-control/discovered-ne[boolean(controller[nsp-model:schema-nodeid='/nsp-ne-control:ne-control/controller'][ne-id='NSP-24'])]
XPath expressions
An XPath expression is an XPath that can be evaluated to produce a list of XPath identifiers. For the purpose of an object filter, the XPath expression must resolve to a NodeSet of NSP model identifiers.
XPath expressions can be chained together using a union “|” operator, which evaluates each subexpression independently into NodeSets and performs a set union operation to combine the NodeSets into a single NodeSet result.
Expressions can be static expressions, which resolve to the same result every time, or wildcard expressions, which can produce different results. The dynamic effect is created by using syntax that does not specifically identify a set of NSP model objects: there is no wildcard character.
Examples:
MDM equipment: component-id='shelf=1/cardSlot=1/card=1/mdaSlot=1/mda=1/port=1/1/1'
Classic equipment: component-id='shelf=1/slot=1/card=1/slot=1/card=1/port=1'
Example of a static expression:
/nsp-equipment:network/network-element[ne-id='10.1.0.0']/hardware-component/port[component-id='shelf=1/cardSlot=1/card=1/mdaSlot=1/mda=1/port=1/1/1' or component-id='shelf=1/cardSlot=1/card=1/mdaSlot=1/mda=1/port=1/1/2'] | /nsp-equipment:network/network-element[ne-id=’10.1.0.1’]/hardware-component/port[component-id='shelf=1/cardSlot=1/card=1/mdaSlot=1/mda=1/port=1/1/3' or component-id='shelf=1/cardSlot=1/card=1/mdaSlot=1/mda=1/port=1/1/4']
Examples of wildcard expressions:
Create a wildcard expression by not including all keys in the predicates.
-
The following expression chooses all objects of type port on NE 1.1.1.1.
/nsp-equipment:network/network-element[ne-id='1.1.1.1']/hardware-component/port
-
The following expression chooses all objects of type port for all NEs.
/nsp-equipment:network/network-element/hardware-component/port
-
The following expression returns all child objects that can respond to the selected telemetry type and counters.
/nsp-equipment:network/network-element[ne-id='10.1.0.0']
Filtering models
Paths for MDM-managed NEs are based on the NE YANG models.
Device model
The NE YANG model used by NSP is network-device-mgr.
-
This model uses device model xpath notation—this means that the filter can support all the paths as implemented by the node. Creating a path using the device model is useful when the object is not supported by, or not defined in, the NSP model.
-
The device model provides a view of the device-specific paths. For example, an SR OS NE defines an LSP object using a path similar to /network-device-mgr:network-devices/network-device[name='10.1.0.0']/root/nokia-state:state/router[router-name='Base']/mpls/statistics/lsp-egress[lsp-name='LSP1'].
The telemetry mapping artifact must contain a definition for the device path for telemetry to be collected.
The following is an example of a network-device-mgr model filter type for an NFM-P managed device. This filter targets a specific object instance by its FDN:
/network-device-mgr:network-devices/network-device[name='10.1.0.0']/root/nokia-nsp-source:fdn[id='fdn:realm:sam:lsp:from-11.50.150.30-id-2']
Equipment model
The nsp-equipment:network model is a normalized NSP YANG model that provides a view of the equipment for all network elements, abstracting the device specifics. Using NSP equipment model identifiers is recommended because the models are supported by NSP applications. In addition, filters based on the NSP equipment model can use operators such as AND or CONTAINS.
For example, the following path represents an individual port./nsp-equipment:network/network-element[ne-id='10.1.0.0']/hardware-component/port[name='1/1/1']
Equipment model information can be found using the Network Inventory API; see the Postman collection on the API Documentation page.
To assemble a filter, find the relevant model details and add predicates and predicate functions as needed. For example, a get port operation provides the path to the port.