Genie Diff

genie diff is used to compare Python datastructures generated by genie parse and genie learn. It is extremely useful in performing stateful network validation before and after any event occurs in a network that could cause the operational state to change.

To see what functionality genie diff offers, execute the following in your linux terminal:

  (genie) bash-4.1$ genie diff --help
  Usage:
    genie diff [commands] [options]

  Example
  -------
    genie diff file1 file2
    genie diff dir1 dir2
    genie diff dir1 dir2 --exclude "age"
    genie diff dir1 dir2 --no-default-exclusion --exclude "age" "uptime"

  Description:
    Diff two feature or parser snapshots saved to file or directory
    Default exclusion can be found at
$VIRTUAL_ENV/lib/python<version>/site-packages/genie/libs/sdk/genie_yamls/pts_datafile.yaml

  Diff Options:
    [file or directory]   file/directory of pre=snapshot
    [file or directory]   file/directory of post-snapshot
    --output OUTPUT       Which directory to store logs, by default it will be current directory
                          (Optional)
    --exclude                     [EXCLUDE [EXCLUDE ...]]
                          Keys to exclude when saving the Feature (Optional)
    --no-default-exclusion
                          Do not use the default exclude keys (Optional)

  General Options:
    -h, --help            Show help
    -v, --verbose         Give more output, additive up to 3 times.
    -q, --quiet           Give less output, additive up to 3 times, corresponding to WARNING, ERROR,
                          and CRITICAL logging levels

Default Exclusion

By default genie diff references a pre-created list of keys to exclude during comparison of datastructures generated using genie parse and genie learn. This list includes typical values that are dynamic/change over time and are generally excluded during comparison such as packet counters, timestamps, uptime, etc.

Note

  1. For Parsers (genie parse), genie diff references the default verification_datafile YAML to find the list of exclude keys for each show-command. This file can be found at: $VIRTUAL_ENV/genie_yamls/<your_os>/verification_datafile.yaml

  2. For Ops (genie learn), genie learn references the default PTS datafile YAML to find the list of exclude keys for each feature. This file can be found at: $VIRTUAL_ENV/genie_yamls/pts_datafile.yaml

The following is an example of using genie diff with the default exclude list during comparison:

(genie) bash-4.1$ genie diff dir1 dir2 --output diff1
1it [00:00,  8.44it/s]
+==============================================================================+
| Genie Diff Summary between directories dir1/ and dir2/                       |
+==============================================================================+
|  File: bgp_nxos_nxos-osv-1_ops.txt                                           |
|   - Diff can be found at diff1/diff_bgp_nxos_nxos-osv-1_ops.txt              |
|------------------------------------------------------------------------------|

A diff file gets created and saved into the directory specified with ‘–output’.

Note

The user must create directories ‘diff1’ and ‘diff2’ containing saved Python datastructures of either genie parse or genie learn prior to using genie diff.

Here is an example of a diff that is observed between the genie learn Ops objects created at two different timestamps. We can see that value for keys ‘session_state’ and ‘state’ changed between the two Ops objects on the same device.

(genie) bash-4.1$ more diff1/diff_bgp_nxos_nxos-osv-1_ops.txt
--- dir1/bgp_nxos_nxos-osv-1_ops.txt
+++ dir2/bgp_nxos_nxos-osv-1_ops.txt
info:
 instance:
  default:
   vrf:
    default:
     neighbor:
      50.1.1.101:
       address_family:
        ipv4 multicast:
+         session_state: active
-         session_state: idle
        ipv4 unicast:
+         session_state: active
-         session_state: idle
        ipv6 multicast:
+         session_state: active
-         session_state: idle
        vpnv4 unicast:
+         session_state: active
-         session_state: idle
        vpnv6 unicast:
+         session_state: active
-         session_state: idle
       bgp_session_transport:
        connection:
+         state: active
-         state: idle
+       session_state: active
-       session_state: idle
      50:1::1:101:
       address_family:
        ipv6 unicast:
+         session_state: active
-         session_state: idle
       bgp_session_transport:
        connection:
+         state: active
-         state: idle
+       session_state: active
-       session_state: idle

Note

As with normal linux diff:

  1. ‘-‘ means this key is now missing or has been modified and this was the old value.

  2. ‘+’ means this key has been added or been modified and this is the current value.

Additional Exclusion

Users can provide additional keys to exclude when using genie diff by specifying them in the argument ‘–exclude’.

The following is a repeat of the previous example but this time we have added argument ‘–exclude ‘state’’ to genie diff to skip comparison of the key ‘state’ between the two Ops objects. As seen in the diff, genie learn now only finds differences between the ‘session_state’ keys.

(genie) bash-4.1$ genie diff dir1 dir2 --output diff1 --exclude 'state'
1it [00:00,  9.43it/s]
+==============================================================================+
| Genie Diff Summary between directories dir1/ and dir2/                       |
+==============================================================================+
|  File: bgp_nxos_nxos-osv-1_ops.txt                                           |
|   - Diff can be found at diff1/diff_bgp_nxos_nxos-osv-1_ops.txt              |
|------------------------------------------------------------------------------|

(genie) bash-4.1$ more diff1/diff_bgp_nxos_nxos-osv-1_ops.txt
--- dir1/bgp_nxos_nxos-osv-1_ops.txt
+++ dir2/bgp_nxos_nxos-osv-1_ops.txt
info:
 instance:
  default:
   vrf:
    default:
     neighbor:
      50.1.1.101:
       address_family:
        ipv4 multicast:
+         session_state: active
-         session_state: idle
        ipv4 unicast:
+         session_state: active
-         session_state: idle
        ipv6 multicast:
+         session_state: active
-         session_state: idle
        vpnv4 unicast:
+         session_state: active
-         session_state: idle
        vpnv6 unicast:
+         session_state: active
-         session_state: idle
+       session_state: active
-       session_state: idle
      50:1::1:101:
       address_family:
        ipv6 unicast:
+         session_state: active
-         session_state: idle
+       session_state: active
-       session_state: idle

Note

As with normal linux diff:

  1. ‘-‘ means this key is now missing or has been modified and this was the old value.

  2. ‘+’ means this key has been added or been modified and this is the current value.

No Exclusion

Users can choose to completely skip using the default exclude list by specifying argument ‘–no-default-exclusion’.

Note

Specifying key ‘–no-default-exclusion’ will result in significantly larger diff between two Ops or parser structures as all the default exclude keys

will now be comapred.

The following is a repeat of the previous example with ‘–no-default-exclusion’ argument, resulting in a larger diff between the two Ops objects:

(genie) bash-4.1$ genie diff dir1 dir2 --output diff1 --no-default-exclusion
1it [00:00, 18.94it/s]
+==============================================================================+
| Genie Diff Summary between directories dir1/ and dir2/                       |
+==============================================================================+
|  File: bgp_nxos_nxos-osv-1_ops.txt                                           |
|   - Diff can be found at diff1/diff_bgp_nxos_nxos-osv-1_ops.txt              |
|------------------------------------------------------------------------------|

(genie) bash-4.1$ more diff1/diff_bgp_nxos_nxos-osv-1_ops.txt
--- dir1/bgp_nxos_nxos-osv-1_ops.txt
+++ dir2/bgp_nxos_nxos-osv-1_ops.txt
info:
 instance:
  default:
   vrf:
    VRF1:
     neighbor:
      55.1.1.101:
+       up_time: 14:41:15
-       up_time: 14:39:48
      55:1::1:101:
+       up_time: 14:41:15
-       up_time: 14:39:48
    default:
     neighbor:
      200.1.1.1:
       bgp_neighbor_counters:
        messages:
         received:
+          keepalives: 2641
-          keepalives: 2637
+          total: 2651
-          total: 2647
+          total_bytes: 50421
-          total_bytes: 50345
         sent:
+          keepalives: 5279
-          keepalives: 5270
         sent:
+          total: 5289
-          total: 5280
         sent:
+          total_bytes: 100604
-          total_bytes: 100433
+       up_time: 14:40:08
-       up_time: 14:38:41
routes_per_peer:
 instance:
  default:
   vrf:
    VRF1:
     neighbor:
      55.1.1.101:
       address_family:
        ipv4 unicast:
+         up_down: 14:41:15
-         up_down: 14:39:48
      55:1::1:101:
       address_family:
        ipv6 unicast:
+         up_down: 14:41:15
-         up_down: 14:39:48
    default:
     neighbor:
      200.1.1.1:
       address_family:
        ipv4 unicast:
+         msg_rcvd: 2651
-         msg_rcvd: 2647
+         msg_sent: 5289
-         msg_sent: 5280
+         up_down: 14:40:09
-         up_down: 14:38:42
        vpnv4 unicast:
+         msg_rcvd: 2651
-         msg_rcvd: 2647
+         msg_sent: 5289
-         msg_sent: 5280
+         up_down: 14:40:09
-         up_down: 14:38:42
        vpnv6 unicast:
+         msg_rcvd: 2651
-         msg_rcvd: 2647
+         msg_sent: 5289
-         msg_sent: 5280
+         up_down: 14:40:09
-         up_down: 14:38:42
(snip)

Note

As with normal linux diff:

  1. ‘-‘ means this key is now missing or has been modified and this was the old value.

  2. ‘+’ means this key has been added or been modified and this is the current value.

Custom Exclusion

Users can create their own custom exclusion list by combining the arguments ‘–no-default-exclusion’ to completely skip the default exclusion list and also provide argument ‘–exclude’ to specify their custom list of keys to skip comparison for.

The following is an example:

(genie) bash-4.1$ genie diff dir1 dir2 --output diff1 --no-default-exclusion --exclude 'up_time' 'msg_rcvd' 'msg_sent'
1it [00:00, 18.94it/s]
+==============================================================================+
| Genie Diff Summary between directories dir1/ and dir2/                       |
+==============================================================================+
|  File: bgp_nxos_nxos-osv-1_ops.txt                                           |
|   - Diff can be found at diff1/diff_bgp_nxos_nxos-osv-1_ops.txt              |
|------------------------------------------------------------------------------|

(genie) bash-4.1$ more diff1/diff_bgp_nxos_nxos-osv-1_ops.txt
--- dir1/bgp_nxos_nxos-osv-1_ops.txt
+++ dir2/bgp_nxos_nxos-osv-1_ops.txt
info:
 instance:
  default:
   vrf:
    default:
     neighbor:
      200.1.1.1:
       bgp_neighbor_counters:
        messages:
         received:
+          keepalives: 2641
-          keepalives: 2637
+          total: 2651
-          total: 2647
+          total_bytes: 50421
-          total_bytes: 50345
         sent:
+          keepalives: 5279
-          keepalives: 5270
         sent:
+          total: 5289
-          total: 5280
         sent:
+          total_bytes: 100604
-          total_bytes: 100433
routes_per_peer:
 instance:
  default:
   vrf:
    default:
     neighbor:
      200.1.1.1:
       address_family:
        ipv4 unicast:
+         up_down: 14:40:09
-         up_down: 14:38:42
        vpnv4 unicast:
+         up_down: 14:40:09
-         up_down: 14:38:42
        vpnv6 unicast:
+         up_down: 14:40:09
-         up_down: 14:38:42
      50.1.1.101:
       address_family:
        ipv4 multicast:
+         state_pfxrcd: active
-         state_pfxrcd: idle
+         up_down: 14:41:16
-         up_down: 14:39:49
        ipv4 unicast:
+         state_pfxrcd: active
-         state_pfxrcd: idle
+         up_down: 14:41:16
-         up_down: 14:39:49
        ipv6 multicast:
+         state_pfxrcd: active
-         state_pfxrcd: idle
+         up_down: 14:41:16
-         up_down: 14:39:49
        vpnv4 unicast:
+         state_pfxrcd: active
-         state_pfxrcd: idle
+         up_down: 14:41:16
-         up_down: 14:39:49
        vpnv6 unicast:
+         state_pfxrcd: active
-         state_pfxrcd: idle
+         up_down: 14:41:16
-         up_down: 14:39:49
(snip)

Note

As with normal linux diff:

  1. ‘-‘ means this key is now missing or has been modified and this was the old value.

  2. ‘+’ means this key has been added or been modified and this is the current value.

Verbose Option

Users can also specify to display unchanged entries in tuple or list by giving the ‘–verbose’ option. This will show all the entries, changed or unchanged, of the iterable in the output diff.

The following is an example:

(genie) bash-4.1$ genie diff before after --verbose
+==============================================================================+
| Genie Diff Summary between file before and after                             |
+==============================================================================+
|  File: before                                                                |
|   - Diff can be found at ./diff_before                                       |
|------------------------------------------------------------------------------|

(genie) bash-4.1$ more ./diff_before
--- before
+++ after
    ospf-neighbor-information:
      ospf-neighbor:
        index[1]:
    -         activity-timer: 38
+     activity-timer: 40
    -     interface-name: ge-0/0/1.0
    +     interface-name: ge-1/0/1.0
          neighbor-address: 105.189.14.121
              neighbor-id: 105.189.14.121
              neighbor-priority: 128
              ospf-neighbor-state: Full

Note

As with normal linux diff:

  1. ‘-‘ means this key is now missing or has been modified and this was the old value.

  2. ‘+’ means this key has been added or been modified and this is the current value.