Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Defining Views for Junos PyEZ Operational Tables that Parse Unstructured Output

 

Junos PyEZ operational (op) Tables for unstructured output extract data from the text output of a CLI command executed on a device running Junos OS or a vty command executed on a given Flexible PIC Concentrator (FPC). A Table is associated with a View, which is used to access fields in the Table items and map them to user-defined Python variables. You associate a Table with a particular View by including the view property in the Table definition, which takes the View name as its argument.

A View maps your user-defined variables to data in the selected Table items. A View enables you to access specific fields in the output as variables with properties that can be manipulated in Python. Junos PyEZ handles the extraction of the data into Python as well as any type conversion or data normalization. The keys defined in the View must be valid Python variable names.

This topic discusses the different components of the View.

Summary of Parameters in Views for Parsing Unstructured Output

Junos PyEZ Views, like Tables, are formatted using YAML. Views that parse unstructured output can include a number of parameters, which are summarized in Table 1.

Table 1: Parameters in Views for Junos PyEZ Op Tables for Unstructured Output

View Parameter

Description

View Name

User-defined identifier for the View.

columns

(Optional) List of column titles in the command output.

eval

(Optional) Associative array, or dictionary, of one or more key-value pairs that map a user-defined key to a string containing a mathematical expression. For each iteration of the data, the expression is evaluated using the Python eval function. The key and the calculated value are added to the data corresponding to that iteration.

exists

(Optional) Associative array, or dictionary, of key-value pairs that map a user-defined key to a string. If the string is present in the output, the variable is set to True, otherwise, the variable is set to False.

fields

(Optional) Associative array, or dictionary, of key-value pairs that map a user-defined key to the name of a nested Table that parses a specific section of the command output.

filters

(Optional) List of one or more keys defined under columns. The final set of data only includes data from the selected columns.

regex

(Optional) List of regular expressions to match desired content.

View Name

The View name is a user-defined identifier for the View. You associate a Table with a particular View by including the view property in the Table definition and providing the View name as its argument.

The following example defines a View named ChassisFanView, which is referenced by the Table’s view parameter:

columns

You can use the columns parameter in a View to extract and parse command output that is formatted in rows and columns.

Consider the following show ospf neighbor command output:

To extract the data, include the columns parameter in the View, and map your Python variable name to the column name. The application stores the key and the value extracted from the command output for that column as a key-value pair in the dictionary for the given item.

The following View extracts the data from each column in the show ospf neighbor command output:

When you retrieve and print the data in the Junos PyEZ application, the data for each neighbor includes the column keys and corresponding data.

user@host:~$ python3 junos-pyez-ospf-neighbors.py

To filter the data to only include data from selected columns, include the filters parameter in the View. For more information, see filters.

Some command output includes column titles that span multiple lines, for example:

To define a multiline column title in a View, set the column key element equal to a list of the words in each row for that title. The following View defines the columns for the previous command output:

Eval Expression (eval)

You can use the optional eval parameter to add or modify key-value pairs in the final data returned by the Table and View. The eval parameter maps a key name to a string containing a mathematical expression that gets evaluated by the Python eval function. You can include the eval parameter in both Tables and Views, and eval can define and calculate multiple values.

When you use eval in a Table, it references the full data dictionary for the calculation, and the key and calculated value are added as a single additional item to the dictionary. When you use eval in a View, the expression is calculated on each iteration of the data, and the calculated value is added to the data for that iteration. If the eval key name matches a key defined in the View, eval replaces the value of that key with the calculated value. If the eval key name does not match a key defined in the View, eval adds the new key and calculated value to the data.

The eval expression can reference the data dictionary returned by the View. The expression must reference data using a Jinja template variable, so that Junos PyEZ can replace the variable with the dictionary when the expression is evaluated.

The following example uses eval in the View definition. The cpu entry modifies the existing value of the cpu field for each item in the data dictionary, and the max entry creates a new key-value pair for each item in the data dictionary.

Consider the following sample output for the show threads vty command:

The View’s eval parameter modifies each cpu entry to omit the percent sign (%). As a result, the data includes '0' instead of '0%'. In addition, it adds a new key, max, and its calculated value for each item.

For examples that use eval in the Table definition, see Eval Expression (eval).

exists

You can use the optional exists parameter in a View to indicate if a string is present in the command output. exists is a dictionary of key-value pairs that map a user-defined Python variable name to the string to match in the command output. If the string is present in the output, the variable is set to True. Otherwise, the variable is set to False.

Consider the show host_loopback status-summary vty command output.

The following Table defines exists to test if the command output includes a No detected wedges string or a No toolkit errors string:

When you use the Table and View to test for the strings and print the resulting values in your Junos PyEZ application, both variables are set to True in this case.

fields

Command output can be lengthy and complex, and you might need different logic to parse different sections of the output. In some cases, you cannot adequately parse the command output using a single Table and View. To parse this type of output, you can include the optional fields parameter in the View. fields is a dictionary of key-value pairs that map a user-defined key to the name of a nested Table that selects a specific section of the command output. Each nested Table can reference its own View, which is used to parse the data selected by that Table.

Consider the show xmchip 0 pt stats vty command output, which has two different sections of data:

The following XMChipStatsView View uses the fields parameter to define two additional Tables, which are used to parse the two different sections of the command output. The _WANPTStatTable and _FabricPTStatTable Tables extract the data from the WAN PT statistics and the Fabric PT statistics sections, respectively. In this case, the Tables use the delimiter parameter to extract and split the data, so they do not need to reference a separate View.

When you retrieve and print the data in the Junos PyEZ application, each key defined under fields contains the data selected and parsed by the corresponding Table.

As another example, consider the show ttp statistics vty command output:

The FPCTTPStatsView View uses the fields parameter to reference multiple nested Tables, which extract the data in the different sections of the output. Each Table references its own View or uses the delimiter parameter to parse the data in that section.

When you retrieve and print the data in the Junos PyEZ application, each fields key contains the data that was extracted and parsed by the corresponding Table.

filters

The columns parameter extracts data from command output that is formatted in rows and columns. When you include the columns parameter in a View, you can optionally include the filters parameter to filter which column data is included in the final output. The filters parameter defines a list of one or more keys defined under columns. The final set of data only includes data from the selected columns. You can provide default filters in the View definition, and you can also define or override filter values in the Junos PyEZ application.

Consider the show ospf neighbor command output:

In the following View, the columns parameter defines keys for all of the columns in the corresponding command output, but the filters parameter only includes the data from the Address and State columns in the data dictionary.

The following Junos PyEZ code first calls get() without any arguments, which retrieves the data using the default list of filters defined in the View. The second call to get() includes the filters argument, which overrides the filter list defined in the View.

When you execute the application, the first call to get() uses the filters defined in the View, and the second call uses the filters defined in the call, which override those defined in the View.

user@host:~$ python3 junos-pyez-ospf-filters.py

regex

You can use the optional regex parameter in a View to match and extract specific fields in the command output. regex is a dictionary that maps keys to regular expressions. If the corresponding Table does not define item: '*', Junos PyEZ combines the regular expressions and matches the result against each line of output. However, if the Table defines item: '*' to extract the data as a single text string, Junos PyEZ instead matches each individual regular expression against the entire text string.

The capturing group defined in the regular expression determines the data that is extracted from the field and stored in the data dictionary. If you define a capturing group, only the value for that group is stored in the data. Otherwise, Junos PyEZ stores the value that matches the full expression. For example, (d+.d+) retrieves and stores a float value from the string search expression, whereas (d+).d+ only stores the integer portion of the data. If you define multiple groups, only the value for the first group is stored.

Junos PyEZ leverages the pyparsing module to define a number of built-in keywords that you can use in place of a regular expression. Table 2 lists the keyword, a brief description, and the corresponding expression, where pp is derived from import pyparsing as pp.

Table 2: regex Parameter Keywords

Keyword

Description

Expression

hex_numbers

Word containing only hexadecimal characters

hex_numbers = pp.OneOrMore(pp.Word(pp.nums, min=1))
    & pp.OneOrMore(pp.Word('abcdefABCDEF', min=1))

numbers

Word consisting of an integer or float value

numbers = (pp.Word(pp.nums) + pp.Optional(pp.Literal('.') +     pp.Word(pp.nums))).setParseAction(lambda i: ''.join(i))

percentage

Word composed of digits and a trailing percentage sign (%)

percentage = pp.Word(pp.nums) + pp.Literal('%')

printables

One or more words composed of printable characters (any non-whitespace characters)

printables = pp.OneOrMore(pp.Word(pp.printables))

word

Word composed of alpha or alphanumeric characters

word = pp.Word(pp.alphanums) | pp.Word(pp.alphas)

words

One or more word strings

words = (pp.OneOrMore(word)).setParseAction(lambda i: ' '.join(i))

Consider the following show icmp statistics command output. Each section of output is under a specific section title, and the data consists of a number and one or more words.

To parse the previous output, the main View defines fields, which references nested Tables and Views that parse each section of output. The nested Views define the regex parameter to match against the data extracted by the corresponding Table.

For example, the _ICMPDiscardsTable Table selects the data under the ICMP Discards section in the command output. The _ICMPDiscardsView View defines two keys, value and name, which map to regular expressions. value matches one or more digits, and name matches one or more words. Because the Table does not define item: '*', the regular expressions are combined and matched against each line of data in that section.

The _ICMPErrorsTable Table selects the data under the ICMP Errors section in the command output. The _ICMPErrorsView View defines the error and name keys and uses the built-in keywords numbers and words in place of explicitly defining regular expressions.

If the Table defines item: '*', the extracted data is considered to be one text string. In this case, each regular expression in the corresponding view matches against the entire string.

Consider the show ithrottle id 0 command output.

The following Table uses item: '*' to extract the data as a single string. The View’s regex parameter defines three regular expressions. Each regex pattern is matched against the entire string. Because the regular expressions define capturing groups, Junos PyEZ only stores the data that matches the group.

When you retrieve and print the data in the Junos PyEZ application, the data includes the three regex items, which contain the value matched by the capturing group for that expression.