Skip to main content

​
Event Composition

A Retis event is a structured data record representing networking activity at a specific point in time. Each event is composed of multiple sections that provide different types of information about the packet or probe.

​
Event Structure

Events follow this general structure: 
<common> <kernel or userspace> <tracking> <drop> <stack trace> <additional sections>
Every event contains:
  • Common section (required): Timestamp and task information
  • Kernel or Userspace section: Probe type and location
  • Optional sections: Additional data based on collectors and packet type

​
JSON Schema

Events are serialized to JSON with the following top-level structure: 
{
  "version": "0.1.0",
  "hostname": "mymachine",
  "kernel": "6.0.8-300.fc37.x86_64",
  "events": [
    {
      "common": { ... },
      "kernel": { ... },
      "packet": { ... },
      "skb": { ... },
      ...
    }
  ]
}

​
Event Sections

Each event can contain the following sections:
​
common
CommonEvent
Always present. Contains timestamp, CPU ID, and task information.
​
kernel
KernelEvent
Kernel probe information (kprobe, kretprobe, or raw tracepoint).
​
userspace
UserEvent
Userspace probe information (USDT probes).
​
tracking
TrackingInfo
Packet tracking information with event index (post-processing).
​
skb_tracking
SkbTrackingEvent
Socket buffer tracking for following packets through the stack.
​
skb_drop
SkbDropEvent
Drop reason when packets are discarded.
​
packet
PacketEvent
Raw packet data with parsed protocol information.
​
skb
SkbEvent
Socket buffer metadata (checksums, GSO, reference counts).
​
netns
NetnsEvent
Network namespace information.
​
dev
DevEvent
Network device information (interface name and index).
​
ovs
OvsEvent
OpenvSwitch datapath events (upcalls, actions, flows).
​
nft
NftEvent
Netfilter/nftables rule matching information.
​
ct
CtEvent
Connection tracking state and tuples.
​
startup
StartupEvent
Collection metadata emitted at startup.

​
Section Grouping

Sections are grouped in an event when they share a common property, such as:
  • Being linked to the same packet
  • Occurring at the same probe point
  • Having the same tracking ID

​
When Sections Are Populated

Which sections appear in an event depends on:
  1. Enabled collectors: Collectors must be enabled via -c flag
  2. Packet type: Protocol-specific data only appears for matching packets
  3. Probe location: Some data is only available at specific kernel functions
  4. Kernel version: Newer kernels provide more information

​
Example Event

Here’s a complete event showing an skb drop: 
{
  "common": {
    "timestamp": "7322460997041",
    "smp_id": 0,
    "task": {
      "pid": 1234,
      "tgid": 1234,
      "comm": "curl"
    }
  },
  "kernel": {
    "symbol": "kfree_skb_reason",
    "probe_type": "kprobe"
  },
  "skb_tracking": {
    "timestamp": "7322460997041",
    "orig_head": "18446623346735780864",
    "skb": "18446623349161350912"
  },
  "skb_drop": {
    "drop_reason": "NOT_SPECIFIED"
  },
  "packet": {
    "len": 98,
    "capture_len": 98,
    "data": "<base64-encoded-packet>"
  },
  "skb": {
    "meta": {
      "len": 98,
      "data_len": 0,
      "hash": 0,
      "ip_summed": 0,
      "csum": 0,
      "csum_level": 0,
      "priority": 0
    }
  }
}
Not all sections appear in every event. The exact composition depends on the collection configuration and the data retrieved at each probe point.

Build docs developers (and LLMs) love

Get started for freeTalk to us