Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Intent-Based Analytics with apstra-cli Utility

IBA with apstra-cli Overview

You can work with Intent-based analytics (IBA) from the Apstra GUI, or for non-production environments you can use the experimental apstra-cli utility (formerly called aos-cli). For information about how to use IBA probes from the GUI, see Probes in the Analytics section. This guide shows you how to use apstra-cli.

Note:

The apstra-cli utility is an experimental tool and has limited support. Do not use it in production environments unless advised by Juniper Support. Some versions of apstra-cli are not intended for certain Apstra releases. Some apstra-cli commands may or may not work between different Apstra releases. It's always best to test a version of apstra-cli with a specific Apstra release in a non-production environment, or contact Juniper Support for assistance.

The apstra-cli utility enables you to extract information from the Apstra server for analytics (and other functionalities). The workflow for IBA probes is as follows:

  1. Install apstra-cli.
  2. Install packages.
  3. Create device agent profiles.
  4. Install device agents.
  5. Install IBA probes.

After probes are instantiated you can use Syslog to send messages to Syslog servers.

Install apstra-cli

Install the apstra-cli utility.

Install Packages

  1. Download the latest Apstra SDK package from Juniper Support Knowledge Base article KB37156.
  2. Custom collector packages enable the collection of telemetry from devices. Extract the collector for your platform (for example, aosstdcollectors_custom_eos-0.1.0.post10-py2-none-any.whl where eos is the platform and 10 is the version).
  3. Collectors require specific Python library packages. If the Apstra environment has Internet access, the files are automatically installed. If the environment doesn't have Internet access, download the following files from the official Python repository. Make sure to download the correct versions:
    • netaddr-0.7.17-py2.py3-none-any.whl
    • gtextfsm-0.2.1.tar.gz
    • pyeapi-0.8.2.tar.gz
  4. From the left navigation menu in the Apstra GUI, navigate to Devices > System Agents > Packages and click Upload Packages.
  5. Either click Choose File and navigate to the custom collector package (and if the Internet is inaccessible, the three (3) Python packages), or drag and drop the file(s) into the dialog window. See example below for Arista devices in an environment without Internet access:
  6. Click Upload to upload the packages to the Apstra server, then close the dialog to return to the summary table view.

Create Agent Profiles

With agent profiles you can specify packages once in the profile, then apply the profile to multiple agents at the same time. Let's create a profile that contains all four packages. (Remember, if your environment has Internet access, you only need to include the custom collector package.)

  1. From the left navigation menu, navigate to Devices > System Agents > Agent Profiles and click Create Agent Profile.
  2. For this example, select EOS from the platform drop-down list.
  3. In the Packages section, select the four uploaded packages to associate them with the agent profile. (If your environment has Internet access, you only need to include the custom collector package.)
  4. Click Create to create the agent profile and return to the summary table view.

For more information about agent profiles, see Agent Profiles.

Create Agents

Now let's create agents for Arista devices and use the agent profile to associate the packages to them. We recommend that you use agent profiles to associate custom collector packages so you can bulk update agents later, as needed, with a single command.

  1. From the left navigation menu, navigate to Devices > System Agents > Agents and click Create Onbox Agent(s).
  2. Enter details for the agent and select the agent profile from the drop-down list as shown in the image below:
  3. To verify that packages have been successfully installed on agents, from the left navigation menu, navigate to Devices > Managed Devices and click the management IP of the device. Click the Agent tab. The Config section lists any installed packages. If you manually uploaded the Python packages (netaddr, gtextfsm and pyeapi) they are listed. If the Apstra server has Internet access, they were automatically uploaded and won't be listed here. (To see all packages installed on the device, log in to the device and check the /tmp/plugins folder.)

Update Agents from apstra-cli

As of apstra-cli build 423, you can update agents with a given agent profile, as needed, based on IP/ID or OS type (os_type) (for example, EOS).

To update agents by IP range with a specific agent profile, use the command system-agents update-profile as shown in the example below. When setting the --profile option, apstra-cli shows available agent profiles. To select, use the up and down arrow keys.

For example.

Install IBA Probes

You can install IBA probes using the Apstra GUI, or for non-production environments you can use apstra-cli. For information about how to create or instantiate predefined probes from the GUI, see Probes in the Analytics section. This section shows you how to use the apstra-cli utility.

All probes described in this document are included in apstra-cli build 412 and later. Probe .j2 files may be made available if the probe file is not built into the apstra-cli build.

Some of these probes require an updated service registry. Download the latest Apstra SDK and extract the json-schemas.tar.gz file. Copy the file to the /home/admin directory of the Apstra server so it is available in the apstra-cli /mytmp directory.

To create probes, use the probe create apstra-cli command. You'll be prompted for additional options.

To select the blueprint ID, use --blueprint and tab-completion.

To list available probes supplied with apstra-cli, use --file and tab-completion. Scroll through the list with the up and down arrow keys.

Some probes need additional Probe template variables.

To see installed IBA probes in the blueprint, navigate to Analytics > Probes.

Apstra IBA Probes Examples

The following section describes how to install some of the most interesting probes which are not available by default.

Packet Drops

Packet drop IBA probes detect an abnormal amount of packet drops on device interfaces that the Apstra software manages, based on interface telemetry that device agents collect.

Filename Description
pkt_discard_anomalies.j2 Detect Fabric interfaces having sustained packet discards

To install the pkt_discard_anomalies.j2 IBA Probe:

Switch Memory Leak (Arista EOS only)

Switch Memory Leak IBA probes detect abnormal memory leaks in specified processes on devices that the Apstra software manages, based on system telemetry that device agents collect. This probe requires device user credentials set in the device agent configuration that has login and access to the device BASH prompt.

Filename Description
memory_usage_threshold_anomalies.j2 Detect memory leaks in specified process on all switches in the Fabric
system_memory_usage_threshold_anomalies.j2 Detect switches having potential memory leaks in the Fabric

The memory_usage_threshold_anomalies.j2 IBA probe requires additional "Probe template variables" for os_family and process.

The only option for os_family is eos for Arista EOS. The (2) options for process are edac-poller and fastcapi or configagent.

Note:

"FastCapi" as service process is valid only for EOS version 4.18. For the newer version of EOS, for example 4.20 and later only ConfigAgent is valid. Take extra care that service name is in lowercase during probe creation. So it should be configagent instead of ConfigAgent.

To install the IBA probe for a second process, repeat the probe create command for the other process.

You can edit the IBA probe name to include the process name.

To install the system_memory_usage_threshold_anomalies.j2 IBA probe:

Fault Tolerance

These (2) probes require apstra-cli build 430 or later.

Filename Description
spine_fault_tolerance.j2 Find out if failure of given number of spines in the fabric is going to be tolerated. Raise anomaly if total traffic on all spines is more than the available spine capacity, with the specified number of spine failures.
lag_link_fault_tolerance.j2 Find out if failure of one link in a server LAG is going to be tolerated. Monitors total traffic in each LAG against total available capacity of the bond, with one link failure. Raise anomaly for racks with more than 50% of such overused bonds, sustained for certain duration.

To install the spine_fault_tolerance.j2 IBA Probe:

Note:

number_of_faulty_spines_to_be_tolerated must be specified.

To install the lag_link_fault_tolerance.j2 IBA Probe: