Rules Overview

Rules

Rules are meant to be free of any hard coding. Think of threshold values; If a threshold is hard coded, there is no easy way to customize it for a different customer or device that has different requirements. Therefore, rules are defined using parameterization to set the default values. This allows the parameters to be left at default or be customized by the operator at the time of deployment. Customization can be done at the device group or individual device level while applying the Playbook in which the individual rules are contained.

Rules that are device-centric are called device rules. Device components such as chassis, system, line cards, and interfaces are all addressed as Topics in the rule definition. Generally, device rules make use of sensors on the devices.

Rules that span multiple devices are called network rules. Network rules:

• Must have a rule-frequency configured

• Must not contain sensors

• Cannot be mixed with device rules in a playbook

To deploy either type of rule, include the rule in a playbook and then apply the playbook to a device group or network group.

Not all of the blocks that make up a rule are required for every rule. Whether or not a specific block is required in a rule definition depends on what sort of information you are trying to get to. Additionally, some rule components are not valid for network rules. Table 1 lists the components of a rule and provides a brief description of each one.

Sensors

When defining a sensor, you must specify information such as sensor name, sensor type and data collection frequency. As mentioned in Table 1, sensors can be one of the following:

• OpenConfig

  For information on OpenConfig JTI sensors, see the Junos Telemetry Interface User Guide.

• Native GPB

  For information on Native GPB JTI sensors, see the Junos Telemetry Interface User Guide.

• iAgent

  The iAgent sensors use NETCONF and YAML-based PyEZ tables and views to fetch the necessary data. Both structured (XML) and unstructured (VTY commands and CLI output) data are supported. For information on Junos PyEZ, see the Junos PyEz Documentation.

• SNMP	Simple Network Management Protocol.

• syslog

  system log

• BYOI	Bring your own ingest – Allows you to define your own ingest types.

• Flow	NetFlow traffic flow analysis protocol

• sFlow

  sFlow packet sampling protocol

When different rules have the same sensor defined, only one subscription is made per sensor. A key, consisting of sensor-path for OpenConfig and Native GPB sensors, and the tuple of file and table for iAgent sensors is used to identify the associated rule.

When multiple sensors with the same sensor-path key have different frequencies defined, the lowest frequency is chosen for the sensor subscription.

Fields

There are four types of field sources, as listed in Table 1. Table 2 describes the four field ingest types in more detail.

/device-group[device-group-name=<device-group>]\
/device[device-name=<device>]/topic[topic-name=<topic>]\
/rule[rule-name=<rule>]/field[<field-name>=<field-value>\
 AND|OR ...]/<field-name>
 

/device-group[device-group-name={{pe-device-group}}]
/device[device-id={{pe-device-name}}]/
topic[topic-name='protocol.l3vpn']
/rule[rule-name=get-interface-details]
/field[sub-interface-index='{{pe-ifl-number}}' 
and interface-name='{{pe-interface-name}}']
/link-state

Vectors

Vectors are useful in helping to gather multiple elements into a single rule. For example, using a vector you could gather all of the interface error fields. The syntax for Vector is:

$field-n can be field of type reference.

The fields used in defining vectors can be direct references to fields defined in other rules:

This syntax allows for optional filtering through the <field-name>=<field-value> portion of the construct. Vectors can also take a time-range option that picks the values from the time-range provided. When multiple values are returned over the given time-range, they are all selected as an array.

The following pre-defined formulas are supported on vectors:

• unique @vector1–Returns the unique set of elements from vector1

• @vector1 and @vector2–Returns the intersection of unique elements in vector1 and vector2.

• @vector1 or @vector2–Returns the total set of unique elements in the two vectors.

• @vector1 unless @vector2–Returns the unique set of elements in vector-1, but not in vector-2

Variables

Variables are defined during rule creation on the Variables page. This part of variable definition creates the default value that gets used if no specific value is set in the device group or on the device during deployment. For example, the check-interface-status rule has one variable called interface_name. The value set on the Variables page is a regular expression (regex), .*, that means all interfaces.

If applied as-is, the check-interface-status rule would provide interface status information about all the interfaces on all of the devices in the device group. While applying a playbook that contains this rule, you could override the default value at the device group or device level. This allows you flexibility when applying rules. The order of precedence is device value overrides device group value and device group value overrides the default value set in the rule.

Functions

Functions are defined during rule creation on the Functions tab. Defining a function here allows it to be used in Formulas associated with Fields and in the When and Then sections of Triggers. Functions used in the when clause of a trigger are known as user-defined functions. These must return true or false. Functions used in the then clause of a trigger are known as user-defined actions.

In Paragon Automation, you can use a Python user-defined function to return multiple values.

For example, consider that you have a function example_function.py that has three return values. When you call the example_function.py in a rule, the first return value in the user-defined function (UDF) is stored in the rule field (Fields tab) that calls the function. You only need to configure return fields, such as r2 and r3, for the remaining two return values in the Return List of the Functions tab.

In the time-series database, the name of Return List fields are prefixed with the name of the rule field that uses the UDF. For example, rule_field_name-r2.

Figure 2 shows an example configuration in the Functions block. The field details are discussed below.

Figure 2: The Functions Block

Triggers

Triggers play a pivotal role in Paragon Insights rule definitions. They are the part of the rule that determines if and when any action is taken based on changes in available sensor data. Triggers are constructed in a when-this, then-that manner. As mentioned earlier, trigger actions are based on Terms. A Term is built with when clauses that watch for updates in field values and then clauses that initiate some action based on what changed. Multiple Terms can be created within a single trigger.

Evaluation of the when clauses in the Terms starts at the top of the list of terms and proceeds to the bottom. If a term is evaluated and no match is made, then the next term is evaluated. By default, evaluation proceeds in this manner until either a match is made or the bottom of the list is reached without a match.

Pre-defined operators that can be used in the when clause include:

• greater-than–Used for checking if one value is greater than another.

  • Returns: True or False

  • Syntax: greater-than <LHS> <RHS> [time-range <range>]

  • Example: //Memory > 3000 MB in the last 5 minutes

    when greater-than $memory 3000 time-range 5m;

• greater-than-or-equal-to–Same as greater-than but checks for greater than or equal to (>=)

• less-than

  • Returns: True or False

  • Syntax: less-than <LHS> <RHS> [time-range <range>]

  • Example: //Memory < 6000 MB in the last 5 minutes

    when less-than $memory 6000 time-range 5m;

• less-than-or-equal-to–Same as less-than but checks for less than or equal to (<=)

• equal-to–Used for checking that one value is equal to another value.

  • Returns: True or False

  • Syntax: equal-to <LHS> <RHS> [time-range <range>]

  • Example: //Queue’s buffer utilization % == 0 

    when equal-to $buffer-utilization 0;

• not-equal-to–Same as equal-to but checks for negative condition (!=)

• exists–Used to check if some value exists without caring about the value itself. Meaning that some value should have been sent from the device.

  • Returns: True or False

  • Syntax: exists <$var> [time-range <range>]

  • Example: //Has the device configuration changed? 

    when exists $netconf-data-change

• matches-with (for strings & regex)–Used to check for matches on strings using Python regex operations. See Python Regular Expressions for details.

  Note:

  LHS, or left hand side, is the string in which we are searching; RHS, or right hand side, is the match expression. Regular expressions can only be used in RHS.

  • Returns: True or False

  • Syntax: matches-with <LHS> <RHS> [time-range <range>]

  • Example: //Checks that ospf-neighbor-state has been UP for the past 10 minutes

    when matches-with $ospf-neighbor-state “^UP$” time-range 10m;

• does-not-match-with (for strings & regex)–Same as matches-with but checks for negative condition

• range–Checks whether a value, X, falls within a given range such as minimum and maximum (min <= X <= max)

  • Returns: True or False

  • Syntax: range <$var> min <minimum value> max <maximum value> [time-range <range>]

  • Example: //Checks whether memory usage has been between 3000 MB and 6000 MB in the last 5 minutes

    when range $mem min 3000 max 6000 time-range 5m;

• increasing-at-least-by-value–Used to check whether values are increasing by at least the minimum acceptable rate compared to the previous value. An optional parameter that defines the minimum acceptable rate of increase can be provided. The minimum acceptable rate of increase defaults to 1 if not specified.

  • Returns: True or False

  • Syntax:

    increasing-at-least-by-value <$var> [increment <minimum value of increase between successive points>]

    increasing-at-least-by-value <$var> [increment <minimum value of increase between successive points>] time-range <range>

  • Example: Checks that the ospf-tx-hello has been increasing steadily over the past 5 minutes.

    when increasing-at-least-by-value $ospf-tx-hello increment 10 time-range 5m;

• increasing-at-most-by-value–Used to check whether values are increasing by no more than the maximum acceptable rate compared to the previous value. An optional parameter that defines the maximum acceptable rate of increase can be provided. The maximum acceptable rate of increase defaults to 1 if not specified.

  • Returns: True or False

  • Syntax:

    increasing-at-most-by-value <$var> [increment <maximum value of increase between successive points>]

    increasing-at-most-by-value <$var> [increment <maximum value of increase between successive points>] time-range <range>

  • Example: Checks that the error rate has not increased by more than 5 in the past 5 minutes.

    when increasing-at-most-by-value $error-count increment 5 time-range 5m;

• increasing-at-least-by-rate–Used for checking that rate of increase between successive values is at least given rate. Mandatory parameters include the value and time-unit, which together signify the minimum acceptable rate of increase.

  • Returns: True or False

  • Syntax:

    This syntax compares current value against previous value ensuring that it increases at least by value rate.

    increasing-at-least-by-rate <$var> value <minimum value of increase between successive points> per <second|minute|hour|day|week|month|year> [time-range <range>]

    This syntax compares current value against previous value ensuring that it increases at least by percentage rate

    increasing-at-least-by-rate <$var> percentage <percentage> per <second|minute|hour|day|week|month|year> [time-range <range>]

  • Example: Checks that the ospf-tx-hello has been increasing strictly over the past five minutes.

    when increasing-at-least-by-rate $ospf-tx-hello value 1 per second time-range 5m;

• increasing-at-most-by-rate–Similar to increasing-at-least-by-rate, except that this checks for decreasing rates.

Using these operators in the when clause, creates a function known as a user-defined condition. These functions should always return true or false.

If evaluation of a term results in a match, then the action specified in the Then clause is taken. By default, processing of terms stops at this point. You can alter this flow by enabling the Evaluate next term button at the bottom of the Then clause. This causes Paragon Insights to continue term processing to create more complex decision-making capabilities like when-this and this, then that.

The following is a list of pre-defined actions available for use in the Then section:

• next

• status

Tagging

Tagging allows you to insert fields, values, and keys into a Paragon Insights rule when certain conditions are met. See Paragon Insights Tagging Overview for more information.

Rule Properties

The Rule Properties block allows you to specify metadata for a Paragon Insights rule, such as hardware dependencies, software dependencies, and version history. This data can be used for informational purposes or to verify whether or not a device is compatible with a Paragon Insights rule.