Network Flow Monitor Agent

This is an on-host agent that passively collects performance statistics related to various communication protocols of interest, beginning with TCP. The statistics can be published in an OpenTelemetry format to an ingestion endpoint.

This application runs on Linux kernel version 5.8 and newer.

Installation

Tip

Instructions are available to deploy across a fleet of EC2 instances or EKS clusters and integrate with Amazon CloudWatch Network Flow Monitor.

Building

Note

Before proceeding, make sure you have a C compiler and Rust development tools available on your system.

Build the application using the command:

cargo build --release

Running

Note

Before starting the application, make sure you've created a cgroup. This usually requires root priveleges or the CAP_SYS_ADMIN capability.

mkdir /mnt/cgroup-nfm
mount -t cgroup2 none /mnt/cgroup-nfm

To run the application with statistics printed to stdout, use the following command. Run this as root or with the CAP_BPF capability.

target/release/network-flow-monitor-agent --cgroup /mnt/cgroup-nfm \
   --publish-reports off --log-reports on

Testing

Run GitHub actions locally using the act CLI:

act workflow_dispatch --privileged

Run only integration tests by building and running the test suite's docker container:

docker build -t integration-tests -f test-data/Dockerfile.test .
docker run --privileged -t integration-tests

Some unit tests need privileges to run:

sudo -E cargo test --features privileged

Integration Tests

EC2 Multi-Distro (integration-tests-ec2.yml)

Runs the agent on real EC2 instances across multiple distributions via SSM. Each instance installs a pre-built binary and runs the test suite.

Tested distributions:

Distro	Kernel	Package	Architectures
Amazon Linux 2	5.10 (Amazon)	RPM	x86_64, arm64
Amazon Linux 2023	6.1 (Amazon)	RPM	x86_64, arm64
Amazon Linux 2023	6.12 (Amazon)	RPM	x86_64
RHEL 9	5.14 (Red Hat)	RPM	x86_64, arm64
SUSE 15 SP6	6.4	RPM	x86_64
Debian 11	5.10 (cloud)	Binary	x86_64
Debian 12	6.1	Binary	x86_64, arm64
Ubuntu 22.04	6.x (HWE)	Binary	x86_64, arm64
Ubuntu 24.04	6.8	Binary	x86_64, arm64

Kubernetes (integration-tests-k8s.yml)

Deploys the agent via Helm chart to pre-created EKS clusters and validates BPF attachment and flow capture. Tests across multiple Kubernetes versions, node AMI families, and architectures. Clusters are managed by CDK (NetworkSonarMonitoringAgentReleaseStressTestCDK).

Test matrix:

K8s Version	AL2023	Bottlerocket	Architectures
1.30	✅	✅	amd64, arm64
1.32	✅	✅	amd64, arm64
1.34	✅	✅	amd64, arm64
1.36 (latest)	✅	✅	amd64, arm64

Known Incompatible Distributions

The following distributions are not supported due to BPF license restrictions in their kernels:

Distro	Kernel	Issue
SUSE 15 SP5	5.14.21 (stock)	Kernel enforces GPL-only on BPF helpers used by the agent
Ubuntu 20.04	5.15 (AWS)	Same GPL restriction + GCC 9 memcmp bug blocks build

Distributions

You can download the official release from our permanent URLs. For more information, refer to link

Versioning

This project follows Semantic Versioning with tags in the format vX.Y.Z:

• X (major): Incompatible changes (e.g., breaking config format, removed features)
• Y (minor): New functionality in a backward-compatible manner (e.g., new metrics, new CLI flags)
• Z (patch): Backward-compatible bug fixes and minor improvements

The agent version is defined in nfm-controller/Cargo.toml and used by the Rust binary at runtime.

Release Tags

When the version in Cargo.toml is updated on main, a GitHub Action automatically creates a vX.Y.Z tag. EKS releases use separate vX.Y.Z-eksbuild.N tags that may point to different commits (e.g., helm chart changes without agent code changes).

Bumping the Version

1. Update the version in nfm-controller/Cargo.toml
2. Merge to main
3. The tag-release workflow creates the tag automatically

Version Sync

The following files are kept in sync automatically via the version-sync workflow:

File	Field	Updated by
nfm-controller/Cargo.toml	version	Developer (source of truth)
charts/.../Chart.yaml	version	Auto-synced from Cargo.toml
charts/.../values.yaml	image.tag	Auto-synced or manual bump

When Cargo.toml version changes in a PR:

• Chart.yaml version is updated automatically
• values.yaml tag is reset to vX.Y.Z-eksbuild.1

When only values.yaml tag changes (e.g., helm chart fix):

• The eksbuild number must increment by exactly 1
• The base version must match Cargo.toml

License

This project is licensed under the Apache 2.0 License.