Skip to main content
The collect command is the primary entry point for tracing packets in the Linux networking stack. It installs probes, gathers events, and can either display them instantly or save them to a file for later processing.

​
Usage

retis collect [OPTIONS]

​
Overview

The collect command uses “collectors” to retrieve data and emit events. Collectors extract data from different parts of the kernel or userspace daemons using eBPF. Some install probes automatically, while each collector specializes in retrieving specific data.

​
Core Options

​
--collectors
string
default:"auto"
Comma-separated list of collectors to enable.Available collectors:
  • auto - Enable all collectors if prerequisites are met
  • skb-tracking - Packet tracking identifiers
  • skb - Packet information
  • skb-drop - Drop reason information
  • ovs - OpenVSwitch data
  • nft - Nftables context
  • ct - Conntrack information
  • dev - Network device information
  • ns - Namespace information
retis collect --collectors skb,skb-drop,ct
​
--probe
string
Add a probe on the given target. Can be used multiple times.Probes follow the [TYPE:]TARGET[/OPTIONS] pattern.Valid types:
  • kprobe or k - Kernel probes
  • kretprobe or kr - Kernel return probes
  • raw_tracepoint or tp - Kernel tracepoints
Examples:
# Add multiple probes
retis collect --probe tp:skb:kfree_skb --probe kprobe:consume_skb

# Use wildcards
retis collect --probe "kprobe:tcp_*"

# Enable stack traces for a specific probe
retis collect -p skb:kfree_skb/stack -p consume_skb

​
Filtering Options

​
--filter-packet
string
Add a packet filter using pcap-filter syntax.
retis collect --filter-packet "tcp port 443"
retis collect -f "arp or icmp"
​
--filter-meta
string
Add a metadata filter to match kernel structure fields.Syntax: sk_buff.member1.[...].memberN.member_leaf [==|<=|>=|!=] value
# Filter by network interface name
retis collect --filter-meta 'sk_buff.dev.name == "eth0"'

# Filter by network namespace
retis collect -m 'sk_buff.dev.nd_net.net.ns.inum == 4026531840'

​
Output Options

​
--out
path
default:"retis.data"
Write events to a file rather than stdout.If the flag is used without a filename, defaults to retis.data.
retis collect --out events.data
retis collect -o  # Uses retis.data
​
--out-rotate
string
Rotate the output file once a size limit is reached.Requires --out. The limit must be suffixed with a size unit (MB, GB).
retis collect --out events.data --out-rotate 64MB
​
--print
boolean
Write events to stdout even if --out is used.
retis collect --out events.data --print
​
--format
enum
default:"multi-line"
Format used when printing events.Options: multi-line, single-line
retis collect --format single-line

​
Advanced Options

​
--stack
boolean
Include stack traces in kernel events.
retis collect --stack
​
--probe-stack
boolean
Automatically add probes based on stack traces.This mode evaluates stack traces and adds additional kprobes at runtime.Requirements:
  • A filter is required (--filter-packet and/or --filter-meta)
  • If no explicit probe is given, uses tp:skb:kfree_skb and tp:skb:consume_skb
retis collect --probe-stack -f "tcp port 80"
​
--cmd
string
Execute a command and terminate collection once done.
retis collect --cmd "ping -c 5 example.com"
​
--allow-system-changes
boolean
Allow system changes needed for full tracing functionality.This includes:
  • Mounting tracefs to /sys/kernel/tracing
  • Creating nftables dummy table (for nft collector)
retis collect --allow-system-changes
​
--kconf
path
Path to kernel configuration file.Default: auto-detect
retis collect --kconf /boot/config-6.3.8-200.fc38.x86_64
​
--utc
boolean
Print timestamps as UTC instead of monotonic.
retis collect --utc
​
-e
boolean
Print link-layer information from packets.
retis collect -e

​
Examples

# Use default collectors and probes
retis collect

​
Common Use Cases

​
Troubleshooting packet drops

retis collect -c skb-drop --probe tp:skb:kfree_skb -f "host 10.0.0.1"

​
Tracing OpenVSwitch flows

retis collect -c ovs,skb-tracking --allow-system-changes

​
Following a specific connection

retis collect -f "tcp port 8080" -m 'sk_buff.dev.name == "eth0"' --stack

​
Limited duration collection

retis collect --cmd "sleep 30" -o capture.data

​
Default Behavior

When no options are specified:
  • All collectors are enabled if prerequisites are met
  • Default probes: tp:net:netif_receive_skb and tp:net:net_dev_start_xmit
  • Events are printed to stdout
  • Multi-line format is used

​
See Also

  • print - Display stored events
  • sort - Sort events by tracking ID
  • pcap - Generate pcap files from events

Build docs developers (and LLMs) love

Get started for freeTalk to us