Configure a Custom Telemetry Service

This topic describes the steps for configuring a customized telemetry service with the XML Transform node, Join node, Select node, and Service Sink node, using BFD-related metrics as an example.

Add an XML Transform Node

A collector pipeline always starts from an XML Transform node, which defines data ingestion. This node specifies the CLI command and defines the parsing logic. The accessor definition extracts the fields of interest from the CLI command output text.

To add an XML Transform node:

Select the XML icon on the Create Telemetry Collector page.
Enter the CLI command in the search box. In this example, we entered show bfd session detail.
Click Execute.
Select a device to run the command, such as Leaf1.
The execution parses the CLI command output and displays the results in tabular format. This processes, referred to as "Accessor Mapping," extracts only the relevant fields.
Click the Choose Fields tab.
Select the fields from the table and click the Add Mapping button next to the desired field. For BFD, we selected the following:
- remote_state: Indicates the remote BFD state.
- session_neighbor: Specifies the IP address of the remote peer.
- session_state: Indicates the local BFD state.
- session_type: Specifies whether the session is single-hop or multihop BFD.
Click Run up to this node—an arrow on top of the node—to test the results. This output displays all field-value pairs for the BFD protocol. This step lets you verify the node test results.The output displays all field and value pairs for the BFD protocol.
The Test Query Results table in the image below shows the results for the ingested data accessors. The BFD protocol output includes all field-value pairs and shows a typical collector output with mixed IPv4 and IPv6 sessions. This example monitors BFD exclusively for IPv4 sessions, excluding IPv6 sessions.
Add a second XML Transform node for BGP.
Since the BFD Protocol is enabled on BGP Sessions, another XML Transform node is required to retrieve BGP-related data.

The second XML Transform node is necessary because although the BFD CLI command provides some useful information, it does not contain all the details we need. Since BFD operates on top of BGP sessions in this scenario, we need to execute a specific BGP CLI command to gather additional contextual information that the BFD CLI output lacks. The second XML Transform node will handle the processing of this supplementary CLI data.

To add a second XML Transform node:
1. Select the XML icon.
2. Enter the CLI command in the search box. In this example, we entered show bgp neighbor.
3. Click Execute.
4. Select the accessors for the second node. For BGP, we selected the following:
  - local-address
  - peer-address
  - table-name
  - address-families
  The second XML Transform node extracts all specified mapped fields from the list of accessors and displays the following fields:
5. Click Run up to this node—an arrow on top of the node— to test the results of the second XML Transform node.

We have collected all necessary data for the BFD and BGP protocols. Next, we'll combine the processed data from both XML Transform nodes using the Join node, as described in the following section.

Merge the Ingested Data Using the Join Node

The Join Node merges two input tables produced by upstream nodes (in our case, two XML Transform nodes). We'll join rows from the two input data sets and define a join condition to generate the final output.

To merge the ingested data using the Join node:

Select the Join icon on the Create Telemetry Collector page.
Click Inner Join Filter .
Select the Join Type. The join type connects the two XML Transform nodes to the Join Node.
You can switch among various types and select the most suitable option for your specific needs. We selected the default type inner.
Assign aliases to each input to reference the names in the join condition. Once you assign aliases, you can access individual input fields through dot notation.

The illustration shows two tables: one with BFD and another with BGP data, each having distinct columns. The goal is to merge them into a unified table with columns from both. The Join node needs a join condition to specify which elements from the original tables will appear in the result. This process requires at least one shared element to act as the primary key for the new table.

In our scenario, session_neighbor and peer_addressin the BGP table share the same value: the remote IP address. These fields serve as the primary key for the join condition. A Boolean expression defines the join condition and evaluates to True when rows from both inputs align. The system then provides access to data from each input node as a dictionary item under its alias.

For our use case, we defined the Join condition as:

(BFD.session_neighbor == BGP.peer_address.split('+')[0])

The .split() function is used for bgp.peer_address because the field includes a port number appended to the IP address, such as 10.1.1.2+60453. To compare tit tosession_neighbor which contains only an IP address, we must trim the port number. Various functions for this standard data cleaning methodology are defined and documented in the Expression Reference Guide. Click the Expression Reference button for detailed descriptions and examples. You can use auto completion to navigate quickly through the list of possible functions and select the right one.
Connect the Inner Join Filter to the XML Transform nodes. Click and drag the round buttons on each node to link the two nodes to the filter.
Test the results of the Join node by clicking the down arrow on the Inner Join Filter
The following image displays the query results and verifies that the BFD session_neighbor and BGP peer_address values match. You can also view other fields ingested through this node across all 12 rows, each representing a single session.

Define the Service Output Using the Select Filter Node

The Select Filter node is a data transformation component that processes input data by applying expression-driven transformations to generate a modified output. The node's primary purpose is to restructure data into a format acceptable to the telemetry service, resulting in producing the service's schema.

A schema consists of two components: keys and values, with each represented as a dictionary. The Select Node processes the incoming data and generates two dictionaries—a keys dictionary and a values dictionary—which together define the complete schema for your service. Its important to carefully determine which elements belong in the keys versus the values during this process.

Understanding Keys and Values in the Telemetry Service
Define Keys and Values in the Select Node

Understanding Keys and Values in the Telemetry Service

Keys serve as identifiers for tracking telemetry data. For example, when monitoring traffic counters, the interface name serves as the key, such as ge-0/0/1. If class-of service is configured, the system tracks traffic counters specific to each traffic queue. In this case, you can add a second key to represent the class or service or queue associated with each interface, such as ge-0/0/1/Queue_0, ge-0/0/1/Queue_1, ge-0/0/1/Queue_2, and so on.

Values refer to the metrics that will be tracked for a specific identity (key combination). For example, the same traffic counters can include values such as TX_PPS, RX_PPS, TX_BPS, RX_BPS, and others.

Note: Ensure the key combination is unique across all rows when configuring a telemetry service in an IBA probe. Key uniqueness is crucial for defining keys. Errors might occur during probe creation if uniqueness is not maintained.

In our example, we'll define a the service keys and values using the following schema:

Keys: Remote_IP (represents the remote BFD peers IP address).
Values: BFD_Local_State, BFD_Remote_State, BFD_Session_Type, and Routing_Zone.

Define Keys and Values in the Select Node

To define keys and values in the select node:

Select the Select Filter node icon on the Create Telemetry page.
From the Select Filter Properties pane, click the Edit button under the Action column.
Select Add Dictionary Item , then select the Expression option from the drop-down menu to add the keys and values.

The following figure shows a keys definition (Remote_IP), with a single key. In this example, the value is BFD.session_neighbor.

Figure 1: Single-Key Example

The following figure shows an example that defines four BFD values. In this example, the specified values are: BFD.session_state, BFD.remote_state, BFD.session_type, and BGP.table_name.

Figure 2: Four BFD Values

By defining values with a direct mapping to the accessor variables, the telemetry service produces output that exactly matches the originally ingested data.

The Select Filter node enables advanced data transformation using Expression-based mapping. Use auto-completion and the Expression Reference page (lower left) for detailed examples and descriptions.
Link the Select Filter node to the Inner Join Filternode. On the Select Filter node, click the down arrow (Run up to this node).
Edit the values for each field.

Begin by identifying possible values for each value field and creating a schema to convert strings into numerical values This allows IBA to process data as a Discrete State and reverse the conversion.

We assigned numerical values to each state based on preference. You can assign values differently but must ensure symmetrical mapping in IBA. Consistent mapping is more important than specific values, as explained later. We'll create an expression to sequentially convert string values into numerical values for each state.

Note: Ensure the expression is written as one continuous line. This guide splits it into multiple lines for readability.

The following figure illustrates BFD Session States (local) with four values: Up, Down, Init, and Failing.

Figure 3: BFD Local Session States with Four Values
The following figure illustrates BFD Remote States with three possible values. Up, Down, and AdminDown.

Figure 4: BFD Remote States with Three Values
The following figure illustrates BFD Session Types with two possible values: Single-Hop BFD and MultiHop BFD session types.

Figure 5: BFD Session Types with Two Values
Specify the mapping for the Routing Zone.

The data transformation in the Routing_Zone, which uses the BGP.table_name, will differ. In our example, we created a mapping between the BGP table names and descriptive strings.

The following figure shows five BGP tables: inet.0, inet6.0, bgp.evpn.0, red.inet.0, and blue.inet.0. By mapping these table names to meaningful identifiers, we can easily determine whether a BFD session belongs to the default BGP table, an overlay BGP session, or a specific routing instance.

Figure 6: Routing Zone Mapping
The following image shows the expected values dictionary configuration for expression-based mapping.
Test the results of the Select Filter node.

Note: The Test Query Results table has color-coded columns. Keys are shown in the green column, while values are shown in the blue column.

Publish the Results Using the Service Sink Node

This node is mandatory for the pipeline. The collector cannot be created without this node.

To publish the results using the Service Sink node:

Select the Service Sink node icon on the Create Telemetry page.
Enter the Service Name and click Create. We entered BFD_Session_Check.
Connect the Inner Join Filter to the XML Transform nodes. Click and drag the round buttons on each node to link the two nodes to the filter.
Verify the Service Sink node Test Results. Click the down arrow (Run up to this node).
Select any device from the list to view the results, such as leaf1.

The collector you just created appears on the Collectors page.

The Service Registry displays the corresponding service. From the registry, you can view the service schema, including the keys and values.

So far, we have defined a new telemetry collector and its service schema definition. However, the system is not running yet because it hasn't been instantiated by any consumer. We'll use the Apstra platform to activate the service and start collecting data from devices.

Next, continue to Create an IBA Probe and Processor.

ON THIS PAGE