advanced/int.rst

In-band Network Telemetry (INT)
===============================

ONOS network configuration for INT application
----------------------------------------------

.. tip::
    Learn more about `ONOS network configuration service
    <https://wiki.onosproject.org/display/ONOS/The+Network+Configuration+Service>`_.

Here's a list of fields that you can configure:

* ``collectorIp``: The IP address of the INT collector, Must be an IP of a host that attached to the fabric. *Required*

* ``collectorPort``: The UDP port that the INT collector will listen on. *Required*

* ``minFlowHopLatencyChangeNs``: The minimum latency change to bypass the flow report
  filter in nanosecond. *Optional, default is 0.*

  We use this value to instruct an INT-capable device to produce reports only for packets
  which hop latency changed by at least ``minFlowHopLatencyChangeNs`` nanosecond from
  the previously reported value for the same flow (5-tuple).

  For example: produce a report only if ``(currentHopLatency - previousHopLatency) > minFlowHopLatencyChangeNs``.
  Some pipeline implementations might support only specific intervals, e.g., powers of 2.

* ``watchSubnets``: List of subnets we want to watch. *Optional, default is an empty list.*

  * Devices will watch packets with source IP or destination IP matched in this list.
  * To watch every packet, use ``0.0.0.0/0``.
  * Note that the pipeline won't watch the INT report traffic.

* ``queueReportLatencyThresholds``: A map that specified thresholds to trigger queue
  report or reset the queue report quota. *Optional, default is an empty map.*

  The key of this map is the queue ID. The devices will only report queues in this map.

  * ``triggerNs``: The latency threshold to trigger queue report in nanosecond. **Required**
  * ``resetNs``: The latency threshold to reset queue report quota in nanosecond. **Optional**

    * When absent, the device will reset the queue report quota when latency is half of ``triggerNs``.

Below is an example of ONOS network configuration for INT application:

.. code-block:: json

    {
        "apps": {
            "org.stratumproject.fabric.tna.inbandtelemetry": {
                "report": {
                    "collectorIp": "10.32.11.2",
                    "collectorPort": 32766,
                    "minFlowHopLatencyChangeNs": 512,
                    "watchSubnets": [
                        "10.32.11.0/24"
                    ],
                    "queueReportLatencyThresholds": {
                        "0": {"triggerNs": 2000, "resetNs": 500},
                        "2": {"triggerNs": 1000, "resetNs": 400}
                    }
                }
            }
        }
    }


Intel DeepInsight integration
-----------------------------

.. note::
    In this chapter, we assume that you already deploy the
    `Intel DeepInsight Network Analytics Software <https://www.intel.com/content/www/us/en/products/network-io/programmable-ethernet-switch/network-analytics/deep-insight.html>`_
    to your setup with a valid license.

    Please contact Intel to get the software package and license of the DeepInsight Network Analytics Software.

Configure the DeepInsight topology
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We use `SD-Fabric utiliity <https://github.com/opennetworkinglab/sdfabric-utils>`_
to convert the ONOS topology and configurations to DeepInsight
topology configuration and upload it.

To install the DeepInsight utility, use the following command:

.. code-block:: bash

    pip3 install git+ssh://git@github.com/opennetworkinglab/sdfabric-utils.git#subdirectory=deep-insight

use the following command to generate the topology configuration file:

.. code-block:: bash

    di gen-topology [-s ONOS_ADDRESS] [-u ONOS_USER] [-p ONOS_PASSWORD] [-o TOPOLOGY-CONFIG-JSON]

For example, we installs ONOS to ``192.168.100.1:8181``

.. code-block:: bash

    di gen-topology -s 192.168.100.1:8181 -o /tmp/topology.json

.. tip::

    Use ``di -h`` to get more detail about commands and parameters

To upload the topology configuration file, go to DeepInsight web UI.
In ``settings`` page there is a ``Topology Settings`` section.

Choose ``Upload topology.json`` and use ``Browse...`` button to upload it.