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}
                    }
                }
            }
        }
    }