Skip to main content
Retis events use a flexible JSON structure where each event consists of multiple optional sections. This architecture allows different collectors to contribute relevant information to the same event.

​
Event File Format

A Retis event file contains a top-level object with metadata and an array of events: 
{
  "version": "0.1.0",
  "hostname": "mymachine",
  "kernel": "6.0.8-300.fc37.x86_64",
  "events": [
    { /* event 1 */ },
    { /* event 2 */ },
    ...
  ]
}

​
Event Sections

Each event is composed of optional sections. The only mandatory section is common, which contains basic timing and task information.

​
Section Overview

Always present. Contains timestamp, CPU, and task information.
{
  "common": {
    "timestamp": 7322460997041,
    "smp_id": 5,
    "task": {
      "pid": 100854,
      "tgid": 100854,
      "comm": "ping"
    }
  }
}
Fields:
  • timestamp: CLOCK_MONOTONIC nanoseconds
  • smp_id: SMP processor ID (CPU number)
  • task.pid: Process ID
  • task.tgid: Thread group ID
  • task.comm: Process/thread name (16 chars max)
Present when event comes from a kernel probe.
{
  "kernel": {
    "symbol": "kfree_skb_reason",
    "probe_type": "kprobe",
    "stack_trace": [
      "kfree_skb_reason+0x1",
      "tcp_v4_rcv+0x15c",
      "ip_local_deliver_finish+0x67"
    ]
  }
}
Fields:
  • symbol: Kernel function name
  • probe_type: One of kprobe, kretprobe, or raw_tracepoint
  • stack_trace: Optional kernel stack trace (when enabled)
Identifies and tracks packets across the kernel network stack.
{
  "skb-tracking": {
    "orig_head": 18446623346735780864,
    "timestamp": 7322460997041,
    "skb": 18446623349161350912
  }
}
Fields:
  • orig_head: Original buffer head pointer (part of tracking ID)
  • timestamp: First-seen timestamp (part of tracking ID)
  • skb: Current sk_buff address (distinguishes clones)
Tracking ID: (timestamp << 64) | orig_head
Socket buffer metadata including checksum, length, and GSO information.
{
  "skb": {
    "meta": {
      "len": 84,
      "data_len": 0,
      "hash": 0,
      "ip_summed": 1,
      "csum": 0,
      "csum_level": 0,
      "priority": 0
    },
    "data_ref": {
      "nohdr": false,
      "cloned": false,
      "fclone": 0,
      "users": 1,
      "dataref": 1
    }
  }
}
Contains the actual packet bytes (base64-encoded) and length information.
{
  "packet": {
    "len": 98,
    "capture_len": 98,
    "data": "AAECAwQFBgcICQoLDA0ODxAREhM..."
  }
}
Fields:
  • len: Original packet length
  • capture_len: Captured length (may be truncated)
  • data: Base64-encoded raw packet bytes
Netfilter connection tracking information.
{
  "ct": {
    "state": "new",
    "ct_status": 392,
    "zone_id": 0,
    "zone_dir": "default",
    "orig": {
      "ip": {
        "src": "10.0.42.5",
        "dst": "1.1.1.1",
        "version": "v4"
      },
      "proto": {
        "icmp": {
          "type": 8,
          "code": 0,
          "id": 1
        }
      }
    },
    "reply": {
      "ip": {
        "src": "1.1.1.1",
        "dst": "10.0.42.5",
        "version": "v4"
      },
      "proto": {
        "icmp": {
          "type": 0,
          "code": 0,
          "id": 1
        }
      }
    }
  }
}
States: established, related, new, reply, related_reply, untracked
Nftables rule verdict information.
{
  "nft": {
    "table": "filter",
    "chain": "input",
    "verdict": "accept",
    "rule_handle": 42
  }
}
OVS datapath and flow information.
{
  "ovs": {
    "datapath": "ovs-system",
    "action": "output:1"
  }
}
Network interface information.
{
  "dev": {
    "ifindex": 3,
    "name": "eth0"
  }
}
Network namespace identification.
{
  "netns": {
    "netns": 4026531840
  }
}
Packet drop reason when available.
{
  "skb_drop": {
    "drop_reason": "NO_SOCKET"
  }
}
First event in file with collection information.
{
  "startup": {
    "retis_version": "1.0.0",
    "cmdline": "retis collect -p kfree_skb_reason",
    "clock_monotonic_offset": {
      "sec": 1234567890,
      "nsec": 123456789
    },
    "machine": {
      "kernel_release": "6.0.8-300.fc37.x86_64",
      "kernel_version": "#1 SMP PREEMPT_DYNAMIC",
      "hardware_name": "QEMU Standard PC"
    }
  }
}

​
Complete Event Example

Here’s a complete event showing multiple sections: 
{
  "common": {
    "timestamp": 8974965787422,
    "smp_id": 5,
    "task": {
      "pid": 100854,
      "tgid": 100854,
      "comm": "ping"
    }
  },
  "kernel": {
    "symbol": "net_dev_start_xmit",
    "probe_type": "raw_tracepoint"
  },
  "skb-tracking": {
    "orig_head": 18446623346735780864,
    "timestamp": 8974965787422,
    "skb": 18446623349161350912
  },
  "dev": {
    "ifindex": 3,
    "name": "eth0"
  },
  "packet": {
    "len": 98,
    "capture_len": 98,
    "data": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8..."
  },
  "ct": {
    "state": "new",
    "ct_status": 392,
    "zone_id": 0,
    "zone_dir": "default",
    "orig": {
      "ip": {
        "src": "10.0.42.5",
        "dst": "1.1.1.1",
        "version": "v4"
      },
      "proto": {
        "icmp": {
          "type": 8,
          "code": 0,
          "id": 1
        }
      }
    },
    "reply": {
      "ip": {
        "src": "1.1.1.1",
        "dst": "10.0.42.5",
        "version": "v4"
      },
      "proto": {
        "icmp": {
          "type": 0,
          "code": 0,
          "id": 1
        }
      }
    }
  }
}

​
Generating the JSON Schema

Retis can generate a complete JSON Schema for event validation and tooling: 
retis schema -o events-schema.json
The schema follows JSON Schema 2020-12 and includes:
  • Complete type definitions for all sections
  • Field descriptions and constraints
  • Enum values for state fields
  • Required vs. optional field markers

​
Using the Schema

# Enable Retis protocol dissection
tshark -r capture.pcapng \
  -o "retis.schema:events-schema.json" \
  -Y 'retis.ct.state=="new"'

​
Event Series

When events are sorted with retis sort, they’re grouped into series by tracking ID: 
{
  "series": [
    {
      "events": [
        { /* event at probe 1 */ },
        { /* same packet at probe 2 */ },
        { /* same packet at probe 3 */ }
      ]
    },
    {
      "events": [
        { /* different packet */ }
      ]
    }
  ]
}
Each series contains events with the same skb-tracking ID, ordered by timestamp.

​
Working with Events

retis collect -c ping -c 1 1.1.1.1
retis print

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us