xdp-monitor(8)

💖 NAME 💖

XDP-monitor — a simple, BPF-powered XDP monitoring tool. bestie, it just watches your XDP stuff and tells you what's up ✨

---

🌸 SYNOPSIS 🌸

XDP-monitor is that girl who monitors various XDP related statistics and events, using the BPF tracepoints infrastructure, and she's trying so hard to be as low overhead as possible. 🫶

⚠️ Heads up: by default, statistics for successful XDP redirect events is disabled, because turning that on means a per-packet BPF tracing overhead. like yeah it's low overhead, but it can still lead to packet processing degradation. not cute. 😭

This tool relies on the BPF raw tracepoints infrastructure in the kernel. periodt.

There's more info on what all the output actually means, both in default (terse) mode and verbose mode, down in the Output Format Description section. iykyk 💅

---

✨ Running xdp-monitor ✨

The syntax for running xdp-monitor is literally this and nothing else:

xdp-monitor [options]

The supported options are:

🎀 The Options, Bestie 🎀

• -i, --interval <SECONDS> — sets the polling interval for collecting all the statistics and displaying them to the output. the unit of interval is in seconds. ⏱️
• -s, --stats — enables statistics for successful redirection. heads up tho: this option comes with a per packet tracing overhead, because it has to record every single successful redirection. 💀
• -e, --extended — starts xdp-bench in "extended" output mode. if you don't set it, xdp-bench starts in "terse" mode. you can switch the output mode live by hitting C-$ while the program is running. see also the Output Format Description section below. 👑
• -v, --verbose — enables verbose logging. supply it twice to get verbose logging out of the underlying libxdp and libbpf libraries. two -vs, double the yapping 🗣️
• --version — shows the application version and exits. slay, short and sweet.
• -h, --help — displays a summary of the available options. your safety net fr fr 🫶

---

🌈 Output Format Description 🌈

By default, redirect success statistics are disabled — use --stats to enable them. The terse output mode is the default, and extended output mode can be activated with the --extended command line option.

SIGQUIT (Ctrl + \) can be used to switch the mode dynamically at runtime. no restart needed, we love a flexible queen 💅

---

🍓 Terse mode 🍓

Terse mode displays at most the following fields:

• rx/s — Number of packets received per second
• redir/s — Number of packets successfully redirected per second
• err,drop/s — Aggregated count of errors per second (including dropped packets)
• xmit/s — Number of packets transmitted on the output device per second

---

🦋 Verbose output mode 🦋

Verbose output mode displays at most the following fields. there are a lot of them, so buckle up bestie 🎀

💜 receive

Displays the number of packets received and errors encountered.

• Whenever an error or packet drop occurs, details of per CPU error and drop statistics will be expanded inline in terse mode.
  • pkt/s — Packets received per second
  • drop/s — Packets dropped per second
  • error/s — Errors encountered per second

🌸 redirect

Displays the number of packets successfully redirected.

• Errors encountered are expanded under the redirect_err field.
• Note that passing -s to enable it has a per packet overhead. 😭
  • redir/s — Packets redirected successfully per second

🔥 redirect_err

Displays the number of packets that failed redirection.

• The errno is expanded under this field with per CPU count.
• The recognized errors are:
  • EINVAL: Invalid redirection
  • ENETDOWN: Device being redirected to is down
  • EMSGSIZE: Packet length too large for device
  • EOPNOTSUPP: Operation not supported
  • ENOSPC: No space in ptr_ring of cpumap kthread
• error/s — Packets that failed redirection per second

✨ enqueue to cpu N

Displays the number of packets enqueued to bulk queue of CPU N.

• Expands to cpu:FROM->N to display enqueue stats for each CPU enqueuing to CPU N.
• Received packets can be associated with the CPU redirect program is enqueuing packets to.
  • pkt/s — Packets enqueued per second from other CPU to CPU N
  • drop/s — Packets dropped when trying to enqueue to CPU N
  • bulk-avg — Average number of packets processed for each event

👑 kthread

Displays the number of packets processed in CPUMAP kthread for each CPU.

• Packets consumed from ptr_ring in kthread, and its xdp_stats (after calling CPUMAP bpf prog) are expanded below this. xdp_stats are expanded as a total and then per-CPU, to associate it to each CPU's pinned CPUMAP kthread.
  • pkt/s — Packets consumed per second from ptr_ring
  • drop/s — Packets dropped per second in kthread
  • sched — Number of times kthread called schedule()
• xdp_stats (also expands to per-CPU counts)
  • pass/s — XDP_PASS count for CPUMAP program execution
  • drop/s — XDP_DROP count for CPUMAP program execution
  • redir/s — XDP_REDIRECT count for CPUMAP program execution

💀 xdp_exception

Displays xdp_exception tracepoint events.

• This can occur due to internal driver errors, unrecognized XDP actions, and due to explicit user trigger by use of XDP_ABORTED.
• Each action is expanded below this field with its count.
  • hit/s — Number of times the tracepoint was hit per second

🧚 devmap_xmit

Displays devmap_xmit tracepoint events.

• This tracepoint is invoked for successful transmissions on output device, but these statistics are not available for generic XDP mode, hence they will be omitted from the output when using SKB mode. 🙈
  • xmit/s — Number of packets that were transmitted per second
  • drop/s — Number of packets that failed transmissions per second
  • drv_err/s — Number of internal driver errors per second
  • bulk-avg — Average number of packets processed for each event

---

🐛 BUGS 🐛

Please report any bugs on Github: https://github.com/xdp-project/xdp-tools/issues — the maintainers are actually so nice about it, no cap. 🫶

---

💖 AUTHOR 💖

The original xdp-monitor tool was written by Jesper Dangaard Brouer. It was then rewritten to support more features by Kumar Kartikeya Dwivedi. This man page was written by Kumar Kartikeya Dwivedi. iconic behavior, honestly 👑

---

and that's the whole page bestie!! this is version V1.6.3, dated DECEMBER 12, 2022, and you've been reading xdp-monitor(8) 💅✨ go monitor some XDP, you've got this 🦋