From 3434f438074bfb8d785d279d26a24cabf4b7ed11 Mon Sep 17 00:00:00 2001 From: Neil McKee Date: Sun, 8 Jun 2025 20:55:14 -0700 Subject: [PATCH] sflow : documentation Update sFlow plugin documentation to reflect the addition of egress-sampling and drop-monitoring. Link the plugin documentation into the table of contents. Type: docs Change-Id: I6bd0e57860ec569fe955fb3f844aa4f24e8d8e25 Signed-off-by: Neil McKee --- docs/developer/plugins/index.rst | 1 + docs/developer/plugins/sflow.rst | 1 + docs/spelling_wordlist.txt | 11 ++++-- src/plugins/sflow/sflow.rst | 77 +++++++++++++++++++++++----------------- 4 files changed, 55 insertions(+), 35 deletions(-) create mode 120000 docs/developer/plugins/sflow.rst diff --git a/docs/developer/plugins/index.rst b/docs/developer/plugins/index.rst index 393eefec535..064ce6afe9c 100644 --- a/docs/developer/plugins/index.rst +++ b/docs/developer/plugins/index.rst @@ -30,6 +30,7 @@ For more on plugins please refer to :ref:`add_plugin`. lb lacp flowprobe + sflow map_lw4o6 mdata dhcp6_pd diff --git a/docs/developer/plugins/sflow.rst b/docs/developer/plugins/sflow.rst new file mode 120000 index 00000000000..fec909f5093 --- /dev/null +++ b/docs/developer/plugins/sflow.rst @@ -0,0 +1 @@ +../../../src/plugins/sflow/sflow.rst \ No newline at end of file diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index b407b39c8c6..51b929e0f60 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -285,6 +285,8 @@ dpdk dpkg dpo dport +dropmon +DROPMON dryrun DS dsa @@ -506,6 +508,7 @@ Init initiatehost inline inlines +insmod instantiation Instantiation Integrations @@ -692,6 +695,7 @@ mldv mmap modelled modernisation +modprobe modularity Monroy mortem @@ -898,6 +902,8 @@ Promisc proto proxying ps +psample +PSAMPLE pseudocode Pseudocode psp @@ -1024,6 +1030,8 @@ setjmp settingupenvironment setUp setUpClass +sflow +sFlow sfr sha Shamir @@ -1239,6 +1247,7 @@ usergroup Usergroup Usermode username +USERSOCK userspace Userspace usr @@ -1384,5 +1393,3 @@ zoomout zx µs oflags -sflow -sFlow diff --git a/src/plugins/sflow/sflow.rst b/src/plugins/sflow/sflow.rst index f9c18488363..6400bd454fb 100644 --- a/src/plugins/sflow/sflow.rst +++ b/src/plugins/sflow/sflow.rst @@ -2,60 +2,71 @@ .. toctree:: -SFlow Monitoring Agent +sFlow Monitoring Agent ====================== Overview ________ -This plugin implements the random packet-sampling and interface -telemetry streaming required to support standard sFlow export -on Linux platforms. The overhead incurred by this monitoring is -minimal, so that detailed, real-time traffic analysis can be -achieved even under high load conditions, with visibility into -any fields that appear in the packet headers. If the VPP linux-cp -plugin is running then interfaces will be mapped to their -equivalent Linux tap ports. +This plugin implements the random packet-sampling, interface +telemetry streaming and packet drop monitoring necessary to support sFlow +export on Linux. The overhead is minimal, allowing detailed real-time +traffic analysis even under high load conditions. The samples, counters and +drops are sent to Linux Netlink channels PSAMPLE, USERSOCK and DROPMON where +tools such as host-sflow at https://sflow.net will receive them and export +standard sFlow. If the VPP linux-cp plugin is running then interfaces will +be mapped to their equivalent Linux tap ports. Example Configuration _____________________ :: + sflow sampling-rate 10000 sflow polling-interval 20 sflow header-bytes 128 + sflow direction both + sflow drop-monitoring enable sflow enable GigabitEthernet0/8/0 sflow enable GigabitEthernet0/9/0 sflow enable GigabitEthernet0/a/0 - ... - sflow enable GigabitEthernet0/a/0 disable Detailed notes ______________ -Each VPP worker that has at least one interface, will create a FIFO -and enqueues samples to it from the interfaces it is servicing that -are enabled. There is a process running in the main thread that will -dequeue the FIFOs periodically. If the FIFO is full, the worker will -drop samples, which helps ensure that (a) the main thread is not -overloaded with samples and (b) that individual workers and interfaces, -even when under high load, can't crowd out other interfaces and workers. - -You can change the sampling-rate at runtime, but keep in mind that -it is a global variable that applies to workers, not interfaces. -This means that (1) all workers will sample at the same rate, and (2) -if there are multiple interfaces assigned to a worker, they'll share -the sampling rate which will undershoot, and similarly (3) if there -are multiple RX queues assigned to more than one worker, the effective -sampling rate will overshoot. +Each VPP worker handling packets on an sFlow-enabled interface will enqueue +1:N random-sampled packet headers to a FIFO that is serviced by a process +in the main thread. These FIFOs are of limited depth. If a FIFO overflows the +worker will drop samples efficiently, which limits the overhead on both workers +and main thread even under high load conditions. + +Similarly, all packets traversing the error-drop arc are enqueued on another +limited-depth FIFO that is also serviced in the main thread. + +The main thread writes the sampled packet headers to netlink-PSAMPLE, +and the dropped packet headers to netlink-DROPMON. It also writes interface +status and counters to netlink-USERSOCK according to the configured +polling-interval. If a tool such as the host-sflow daemon at https://sflow.net +is running locally (with its vpp module enabled) then it will receive them and +export standard sFlow. + +If the VPP linux-cp plugin is running, the mapping from vpp interface to +Linux interface is included in the netlink-USERSOCK feed, allowing the +host-sflow daemon to export with either numbering model. + +For efficiency, the workers take advantage of the fact that sampling all +packets at 1:N is the same as sampling 1:N from each interface. The +same principle allows for sampling on "rx", "tx" or "both" directions +without incurring additional overhead. + +If the configured sampling-rate is too aggressive for the current traffic +level the agent will drop samples, but information about this "clipping" is +also communicated to the sFlow collector. External Dependencies _____________________ -This plugin writes packet samples to the standard Linux netlink PSAMPLE -channel, so the kernel psample module must be loaded with modprobe or -insmod. As such, this plugin only works for Linux environments. - -It also shares periodic interface counter samples vi netlink USERSOCK. -The host-sflow daemon, hsflowd, at https://sflow.net is one example of -a tool that will consume this feed and emit standard sFlow v5. +This plugin only works on Linux platforms. +The Linux kernel "psample" module must be loaded with modprobe or insmod. +The open source host-sflow daemon is at https://sflow.net. +The sFlow v5 spec is published at https://sflow.org. -- 2.16.6