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.
    Staged changes in physical tab: 2D network topology with spine-leaf architecture. Leaf3 node highlighted, connected to spine1 and spine2.
  2. In the Selection section that appears in the right panel, on the Device tab, click Execute CLI Command.
    Network management interface showing connections between devices like leaf3, spine1, and spine2. Selected leaf3 device info includes deploy mode, serial number, management IP, OS, operation mode, hostname, and configuration details.
    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.
    User interface for executing CLI commands on a network device. Highlights: executes show commands, supports auto-completion, piping, XML, JSON modes, and copy to clipboard.
    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.

    XML output showing BFD session details on a Juniper device. Session with neighbor 10.0.0.0 is active with state Up.
    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.
    Screenshot of a network interface showing CLI command execution for BFD session details: address, state, interface, detect time, transmit interval, and multiplier.

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.
    Service Registry interface in Juniper Apstra, showing navigation menu with options like Devices and Telemetry. Main area offers buttons for creating or importing service schemas, but currently shows No items.
  2. In the dialog box that opens, define your schema. The schema determines how you want the collector output to be structured.
    User interface displaying CLI command execution and service schema editing. Command 'show bfd session' reveals BFD session status. Service schema named BFD_Status with telemetry key 'neighbor' set as string. User instructed to use IP address as key and state as value, then click Update to save changes.
  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.
    Juniper Apstra UI showing navigation to Collectors under Devices. Sidebar options include Blueprints, Design, Resources, and more. Collectors highlighted. Main area lists OS details, shows no items. Create Collector button highlighted.
  2. Select the existing service schema (BFD) you created in Create a Service Schema, the click Next.
    User interface for telemetry collector creation in Service step. Selected service is BFD with remove option. Teal Next button highlighted.
  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.
    UI for creating a telemetry collector in a network system. OS: junos; OS Version: 22.2r2. Vendor: Juniper. Devices listed with IP, Hostname, and Model. Navigation buttons: Previous, Next.
    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).
    Screenshot of a telemetry collector interface showing BFD session command input, execution button with IP dropdown, and session output details like state and transmit rates.
  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.
      Telemetry collector interface showing options for data field mapping. Mapping tab is selected with options to filter fields and add mappings. Command used is show bfd session, mapping session-neighbor to neighbour key. Expand, collapse, and submit buttons available.
    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.
      User interface for creating a telemetry collector with tabs for Service, Platform, Command, and Mapping. Options for session-state under bfd-session, mapping like Map to Value, Map to Key neighbour, and value source set to Field. Buttons for Check Schema, Previous, and Submit.
    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.

User interface for creating a telemetry collector with advanced mapping view selected, command input 'show bfd session', test query results table showing IP addresses with status 'Up', and submit button to save configuration.

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.

Telemetry collector interface with Mapping View set to Advanced. Shows data accessors like table and value with a Value Expression set to int value. Option to enable relaxed schema validation. Red arrows and numbers highlight areas.