Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Creating a Custom Telemetry Collector

SUMMARY This topic describes the steps required to create a custom telemetry collector.

In this topic, we'll walk you through creating your own custom telemetry service using BFD. In our example, the telemetry service collects the state of the BFD sessions that you just configured. Our goal is to alert operations that a BFD session is down.

Execute the CLI Command

Starting in Apstra version 4.2.0, you can run CLI show commands for Junos devices directly from the Apstra GUI. Although you can run the show commands without opening a CLI session, its primary purpose is to help you create your own custom telemetry collectors.

You can execute CLI commands from within a staged or active blueprint (shown in our example), or from the Devices > Managed Devices page.

To execute the CLI command:

  1. From your deployed blueprint, select Analytics > Staged Physical Topology (or Staged > Physical > Nodes), then select your Juniper device node.
  2. In the Selection section that appears in the right panel, on the Device tab, click Execute CLI Command.
    In the dialog box that opens, select how you want to view the results: Text Mode, XML Mode, or JSON mode. Below are examples of Text Mode and XML Mode.
    Note:

    The CLI supports only Junos show commands. You cannot run commands that affect the device state, such as request system reboot. For information about the various show commands, see the CLI User Guide for Junos OS.

    Now, run the same show command (show route summary), but select XML Mode this time.

    In the XML output, the XML path (BFD session) information is highlighted. This session information is what we'll use to create our telemetry collection service.

Identify the Key and Value of Interest from the CLI Output

This example shows you how to use the CLI show command to view the neighbor addresses and state information (Up or Down) for your BFD session.
  1. Enter the CLI show command (in this example, show bfd session).
  2. Click Execute to view the BFD session information.

Create a Service Schema

To create a custom service collector, you first need to create a service schema to define how you want your data to be structured and stored.
Note:

A single telemetry service schema can have multiple collectors associated with it.

  1. From the left navigation menu, navigate to Devices > Service Registry, then click the Create Service Schema.
  2. In the dialog box that opens, define your schema. The schema determines how you want the collector output to be structured.
  3. Map the Telemetry Keys and Value Type.
    The telemetry key and value type is collection of key-value pairs in Apstra and are defined as follows:

    • Telemetry key: String that identifies the interface name.

    • Value type: Piece of data that the probe executes against. The value type is usually a string (text), but could also be an integer (whole number).

    As shown in our example in Step 2, we defined the Telemetry key as neighbor and the Value Type as string.
  4. Click Update to finish creating your schema.

Create a Collector

So far, you defined the data to want to collect and how the data will be organized and structured. Our final step is to create a collector.
Note:

A single telemetry service schema can have multiple collectors associated with it.

To create a collector:
  1. From the left navigation pane, navigate to Devices > Collectors > Create Collector.
  2. Select the existing service schema (BFD) you created in Create a Service Schema, the click Next.
  3. Select the platform (OS, OS Variant, OS version, and Model) and devices to target for your telemetry collection. Defining a mix of these inputs enables you to be very broad or very granular. For example, you might have a use case where you want to apply telemetry just on the border leaf devices.
    1. Select the OS type , either junos or junos-evo.
      For more information on Junos-evo (also known as Junos OS Evolved) see the Junos OS Evolved documentation.
      Note:

      If you do not define a Junos-evo collector for Junos-evo devices, the collector uses the corresponding Junos definition. This means, if you use the same command between Junos and Junos-evo, you can create a single Junos collector definition for that service. If the command resides only on Junos-evo, you'll want to create a single collector definition for Junos-evo.

    2. Select the OS Variant the device belongs to and determine the CLI schema for a given device.
    3. Select the minimum OS Version the device must run for the collector to execute. If multiple collector definitions, with different OS versions exist for the same service, the collector automatically chooses the one closest to the version the device is running.
    4. (Optional) Specify a Model or a regular expression to filter based on a device model or series.
      The table shows a list of target devices currently managed in Apstra and matches the applied combination of filters.
    5. Click Next.
  4. Execute the CLI command.
    Use the show command to gather the data you want to collect from the device (in this example, show bfd session).
  5. Map the Keys and Value.
    So far, we've defined the service schema, the target platforms, and the CLI command the custom telemetry collector will execute. Next, we'll map the key(s) and value type you defined in your schema earlier.
    1. To map the keys, click Expand All to search for the RPC value you want to map.
    2. Click Add Mapping.
    3. Assign session-neighbor to the key (in this example, neighbor).
    4. To map the value, select Field as the Value source. In our example, we populated the value based on the dynamic session-state field returned by the CLI command.
    5. Search for the session-state field, then click Add Mapping.
    6. Assign session-state to map the value, then click Submit.

Validate That the Collector Is Working

Finally, in Advanced view, validate that the collector is working. Verify that the query and test results match your expected results.

Congratulations! You successfully created a collector.

Note:

When you define the integer (number) values for a collector, you might need to enter a value expression for the collector to function. This is because Junos occasionally reports number data as a string. Before the collector can be processed, you must perform a conversion from string to integer on the Apstra side.

To define the integer (number) values for a collector, enter int(value) into the Value Expression field and click Submit.