Skip to main content
Retis exposes data and APIs in different ways, including event storage at collection time and the Python API (built-in interpreter and library). This page covers what is considered stable in terms of compatibility across versions and what is not.

​
Events File Format

When collecting events, Retis can store events in a file for later post-processing (retis.data by default).

​
Format Stability

The event file format itself is not guaranteed to be stable across time in any way. It is not recommended to use it directly.

​
Forward Compatibility

Starting with Retis 1.5.0, events collected and stored with a version of Retis can be read with newer versions of Retis, across a given major version.
Events collected with Retis v1.5.0 can be read with Retis v1.6.x, but might not work with Retis v2.y.x.

​
Examples

# Collect with v1.5.0
retis-1.5.0 collect -o events.data

# Read with v1.6.0
retis-1.6.0 print -i events.data
# ✓ This works - same major version

​
Recommendations

  • Use the same major version for collecting and processing events
  • Don’t parse the binary format directly - use Retis commands or Python API
  • Archive events with version info - include the Retis version when archiving event files
  • Re-collect for major upgrades - if upgrading to a new major version, plan to re-collect events

​
Python API and Events

Python can be used to post-process events, with both events and an API exposed for custom processing.
The Python API is not considered stable across releases at the moment.

​
Current Status

  • Stability: Unstable - subject to change between releases
  • Compatibility: Not guaranteed between versions
  • Documentation: See Python bindings documentation

​
Working with the Python API

While the Python API is evolving:
  • Expect breaking changes between releases
  • Pin your Retis version if using Python processing in production
  • Test your Python scripts after upgrading Retis
  • Check release notes for API changes
The Retis team is working toward stabilizing the Python API in future releases. Community feedback on the API design is welcome.

​
Command-Line Interface

​
Stability Guarantees

The Retis command-line interface follows these compatibility guidelines:
  • Commands: Core commands (collect, print, sort, pcap) are stable
  • Options: Common options are generally stable within major versions
  • Output format: Text output format may change between minor versions
  • Exit codes: Standard exit codes (0 for success, non-zero for errors) are stable

​
Deprecation Policy

When commands or options are deprecated:
  1. A warning is shown in the current release
  2. The feature remains functional for at least one minor version
  3. Removal occurs in the next major version

​
Kernel Compatibility

Retis is designed to work with modern Linux kernels that support eBPF and BTF.

​
Minimum Requirements

  • Kernel version: Generally, kernels >= 5.x with BTF support
  • eBPF features: Full BPF support with BTF type information
  • Configuration: See Requirements for kernel config details

​
Testing

Retis is regularly tested on:
  • Recent Fedora releases (including Rawhide)
  • RHEL 8.6+ and RHEL 9
  • CentOS Stream 8 and 9
  • Ubuntu Jammy
While Retis should work on other distributions meeting the kernel requirements, the distributions listed above receive regular testing and validation.

​
Upgrade Guidelines

​
Minor Version Upgrades (e.g., 1.5.x → 1.6.x)

1

Review release notes

Check for any new features or deprecation warnings.
2

Test existing workflows

Verify that your existing commands and profiles still work.
3

Update scripts if needed

If you use the Python API, test and update your scripts.

​
Major Version Upgrades (e.g., 1.x → 2.x)

1

Review breaking changes

Major versions may include breaking changes - carefully review the changelog.
2

Plan for re-collection

Old event files may not be compatible - plan to re-collect data if needed.
3

Update Python scripts

The Python API may have significant changes requiring script updates.
4

Test in non-production first

Validate the upgrade in a test environment before production use.

​
Getting Help

If you encounter compatibility issues:
  • Check the GitHub issues for known problems
  • Report new compatibility issues on GitHub
  • Include your Retis version (retis --version) and kernel version (uname -r) when reporting issues

Build docs developers (and LLMs) love

Get started for freeTalk to us