Skip to main content
Collectors are optional data retrievers and event section producers used in the collection mode (the collect sub-command). They are responsible for handling specific data (e.g., skb) or logical parts of the networking stack (e.g., ct).

​
What are Collectors?

Collectors work behind the scenes to extract meaningful information from the kernel and userspace daemons using eBPF. Each collector specializes in retrieving specific types of data:
  • Some collectors install probes automatically (like skb-drop and nft)
  • Others only retrieve data when it’s available in probe arguments (like skb and ct)
  • Advanced collectors can track packets through userspace daemons (like ovs)

​
Enabling Collectors

The set of collectors to use is controlled by the --collectors (or -c) argument: 
# Use default collectors (auto mode)
retis collect

# Explicitly enable specific collectors
retis collect -c skb,skb-drop,ct

# Mix explicit and auto modes
retis collect -c skb,auto

​
Auto Mode

If collectors are not explicitly requested, Retis uses the auto mode by default. In this mode:
  • All collectors are started if their prerequisites are met
  • If a collector’s prerequisites aren’t met, it’s silently skipped
  • No error is returned

​
Explicit Mode

When collectors are explicitly requested:
  • They become mandatory
  • If prerequisites aren’t met, Retis will fail with an error
  • This ensures your collection has the data you expect

​
Mixed Mode

You can combine both approaches: 
retis collect --collectors skb,auto
This requires the skb collector to start (failing otherwise), while allowing other collectors to start only if their prerequisites are met.

​
Available Collectors

skb

Provides insights into socket buffer (struct sk_buff) data structures, including packet metadata, checksums, and offload information.

skb-tracking

Reports tracking information (unique IDs) for packets to reconstruct in-kernel packet flows.

skb-drop

Provides information about why packets were dropped, including drop reason codes.

ct

Reports connection tracking (conntrack) information from socket buffers, including state and protocol-specific data.

nft

Provides insight into Netfilter rules and actions, tracking packet flow through nftables.

ovs

Retrieves OpenVSwitch-specific data and tracks packets through the userspace daemon.

dev

Provides information about network devices from struct net_device or socket buffers.

ns

Retrieves namespace information, currently supporting network namespaces.

​
Collector Architecture

​
Data Flow

Collectors integrate into Retis’s event collection pipeline:
  1. Probe Installation: Some collectors register probes on specific kernel functions or tracepoints
  2. Data Retrieval: When probes fire, collectors extract relevant data using eBPF
  3. Event Section Creation: Collectors produce event sections that are combined into complete events
  4. Post-Processing: Event sections can be processed by Retis’s post-processing commands

​
Event Sections

The event sections produced by collectors do not always map 1:1. For example:
  • The skb collector produces both skb and packet event sections
  • Multiple collectors can contribute to a single event
  • Some collectors produce sections conditionally based on available data
See the Events documentation for detailed information about event sections.

​
Collector Comparison

CollectorInstalls ProbesRequires Kernel ConfigWorks With
skbNoNonestruct sk_buff *
skb-trackingNo (uses core tracking)Nonestruct sk_buff *
skb-dropYes (1 tracepoint)Nonestruct sk_buff *
ctNoCONFIG_NF_CONNTRACKstruct sk_buff *
nftYes (1 kprobe)CONFIG_NF_TABLESstruct nft_traceinfo *
ovsYes (multiple probes + USDT)OVS kernel modulestruct sk_buff *
devNoNonestruct net_device *, struct sk_buff *
nsNoNonestruct net *, struct sk_buff *, struct net_device *

​
Prerequisites and Requirements

Each collector may have specific prerequisites:

​
Kernel Configuration

  • ct: Requires CONFIG_NF_CONNTRACK=y or the nf_conntrack module loaded
  • nft: Requires CONFIG_NF_TABLES=y or the nf_tables module loaded
  • ovs: Requires the OpenVSwitch kernel module loaded

​
System Setup

  • nft: Requires nftables trace rules (can be installed automatically with --allow-system-changes)
  • ovs: Requires USDT support compiled into ovs-vswitchd for userspace tracking

​
Kernel Types

Collectors are automatically activated when their known kernel types appear in probe arguments:
  • struct sk_buff *: Activates skb, skb-tracking, ct, dev, ns collectors
  • struct net_device *: Activates dev, ns collectors
  • struct net *: Activates ns collector
  • struct nft_traceinfo *: Activates nft collector

​
Usage Examples

​
Basic Collection

# Auto mode - all available collectors
retis collect

# Specific collectors for packet drops
retis collect -c skb,skb-drop

​
With Filtering

# Collect TCP traffic on port 443
retis collect -c skb,ct,nft -f 'tcp port 443'

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

​
With Probes

# Add custom probes with collectors
retis collect -c skb,skb-drop -p skb:kfree_skb -p consume_skb

# Use with profiles
retis -p generic collect -c skb,ct,nft

​
Output Options

# Save to file for post-processing
retis collect -c skb,skb-tracking -o events.json

# Save and print to console
retis collect -c skb,skb-tracking -o events.json --print

​
Collector-Specific Options

Some collectors have their own command-line options:
  • skb: --skb-sections to control which skb metadata to retrieve
  • nft: --nft-verdicts to choose which verdicts to report
  • ovs: --ovs-track to enable userspace tracking, --ovs-enrich-flows to query OVS daemon
See individual collector pages for detailed option descriptions.

​
Next Steps

Explore Collectors

Learn about each collector in detail

Event Sections

Understand event section formats

Filtering

Learn to filter collected events

Post-Processing

Process and analyze collected data

Build docs developers (and LLMs) love

Get started for freeTalk to us