sflow

sFlow

Go library for decoding sFlow v5 datagrams.

Getting started

The decoder takes any io.Reader containing a raw sFlow v5 packet and returns the parsed structure, or an error:

decoder := sflow.NewDecoder(reader)
dgram, err := decoder.Decode()
// dgram contains Version, AgentIP, Samples, etc.
// Each sample (FlowSample, CounterSample, ...) contains typed Records.

Trying it out

A simple way to test out the decoder is by running host-sflow through Docker:

docker run --rm \
  -e "COLLECTOR=127.0.0.1" \
  -e "NET=host" \
  --net=host \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  sflow/host-sflow

host-sflow will now send UDP packets from your host traffic to port 6343. We provide a simple example in this repo that will listen on the same port, decode them and print them to stdout. To test it out, in another terminal, run:

go run github.com/gravwell/sflow/example

Which will produce output similar to this:

2026/02/19 14:27:32 [OK] Packet #1 from 127.0.0.1:43439: Version:5 IPVersion:1 AgentIP:10.0.0.134 SubAgentID:100000 SequenceNumber:55 Uptime:1642041 SamplesCount:1
2026/02/19 14:27:32   Sample[0] CounterSampleExpanded: Format:4 Length:760 SequenceNum:55 SourceIDType:2 SourceIDIndex:1 RecordCount:11
2026/02/19 14:27:32     Record[0] *datagram.VirtNode: &{RecordHeader:{Format:2100 Length:28} Mhz:2500 CPUs:24 Memory:58588684288 MemoryFree:16246149120 NumDomains:0}
2026/02/19 14:27:32     Record[1] *datagram.HostAdapters: &{RecordHeader:{Format:2001 Length:68} Adapters:[{IFIndex:6 MACAddresses:[[200 163 98 18 192 115 0 0]]} ...]}
2026/02/19 14:27:32     Record[2] *datagram.MIB2UDPGroup: &{RecordHeader:{Format:2010 Length:28} UDPInDatagrams:6369235 UDPNoPorts:3190 UDPInErrors:2511 UDPOutDatagrams:8229427 UDPRcvbufErrors:2}
...

Implementation Status

All sample containers (FlowSample, CounterSample, FlowSampleExpanded, CounterSampleExpanded, DiscardedPacket) are implemented.

Legend: ✅ = implemented, ✅✅ = implemented with test coverage, ❌ = not implemented

Counter Records (Enterprise = 0)

Flow Records (Enterprise = 0)

Unknown sample formats decode as UnknownSample with raw data preserved. Unknown flow and counter record formats decode as UnknownRecord with raw data preserved. This allows the decoder to process datagrams containing unimplemented or vendor-specific structures without error.

Want a structure implemented or tested? Send us a raw sFlow packet capture containing it. PRs are welcome!

Architecture

• sflow.go: Top-level API
• datagram/: Low-level XDR types matching sFlow wire format
• decoder/: Higher-level decoded types with proper Go field names
• xdr/: RFC 4506 XDR encoding/decoding primitives
• internal/cmd/testgen/: Utility for capturing live sFlow packets and generating test cases

Security

The decoder protects against OOM attacks by limiting datagrams to 65,536 bytes via io.LimitedReader and validating all count fields against remaining bytes before allocation.

Testing

The internal/cmd/testgen binary captures live sFlow packets as .bin files. Run sflowtool-ref.bash on the captured files to generate .json reference output from the official sflowtool (via Docker) for validation.

References

• https://sflow.org/developers/structures.php
• https://datatracker.ietf.org/doc/html/rfc3176 (sFlow v5)
• https://datatracker.ietf.org/doc/html/rfc4506 (XDR)