ebpf

README

Note

This package is a fork of the weaveworks tcptracer-bpf package which focused on tracing TCP state events (connect, accept, close) without kernel specific runtime dependencies.

This fork adds support for UDP, as well as collection of metrics like bytes sent/received. It also opts for event collection via polling (using BPF maps) instead of being pushed event updates via perf buffers.

tracer-bpf

tracer-bpf is an eBPF program using kprobes to trace TCP/UDP events (connect, accept, close, send_msg, recv_msg).

The eBPF program is compiled to an ELF object file.

tracer-bpf also provides a Go library that provides a simple API for loading the ELF object file. Internally, it is using a fork of the cilium ebpf package.

tracer-bpf does not have any run-time dependencies on kernel headers and is not tied to a specific kernel version or kernel configuration. This is quite unusual for eBPF programs using kprobes: for example, eBPF programs using kprobes with bcc are compiled on the fly and depend on kernel headers. And perf tools compiled for one kernel version cannot be used on another kernel version.

To adapt to the currently running kernel at run-time, tracer-bpf creates a series of TCP connections with known parameters (such as known IP addresses and ports) and discovers where those parameters are stored in the kernel struct sock. The offsets of the struct sock fields vary depending on the kernel version and kernel configuration. Since an eBPF programs cannot loop, tracer-bpf does not directly iterate over the possible offsets. It is instead controlled from userspace by the Go library using a state machine.

Documentation

Index

• Constants
• type Batch
  • func ToBatch(data []byte) *Batch
• type BindSyscallArgs
• type ClassificationProgram
• type Conn
• type ConnDirection
• type ConnFamily
  • func (c ConnFamily) String() string
• type ConnFlags
• type ConnStats
  • func (cs ConnStats) ConnectionDirection() ConnDirection
  • func (cs ConnStats) IsAssured() bool
• type ConnTuple
  • func (t ConnTuple) DestAddress() util.Address
  • func (t ConnTuple) DestEndpoint() string
  • func (t ConnTuple) Family() ConnFamily
  • func (t ConnTuple) SourceAddress() util.Address
  • func (t ConnTuple) SourceEndpoint() string
  • func (t ConnTuple) String() string
  • func (t ConnTuple) Type() ConnType
• type ConnType
  • func (c ConnType) String() string
• type ConntrackTelemetry
• type ConntrackTuple
  • func (t ConntrackTuple) DestAddress() util.Address
  • func (t ConntrackTuple) DestEndpoint() string
  • func (t ConntrackTuple) Family() ConnFamily
  • func (t ConntrackTuple) SourceAddress() util.Address
  • func (t ConntrackTuple) SourceEndpoint() string
  • func (t ConntrackTuple) String() string
  • func (t ConntrackTuple) Type() ConnType
• type PIDFD
• type PortBinding
• type ProtocolStack
• type ProtocolStackWrapper
• type TCPState
• type TCPStats
• type Telemetry
• type UDPRecvSock

Constants

const BatchSize = 0x4

const SizeofBatch = 0x1f0

const SizeofConn = 0x78

Types

type Batch

type Batch struct {
	C0        Conn
	C1        Conn
	C2        Conn
	C3        Conn
	Id        uint64
	Cpu       uint32
	Len       uint16
	Pad_cgo_0 [2]byte
}

func ToBatch

func ToBatch(data []byte) *Batch

ToBatch converts a byte slice to a Batch pointer.

type BindSyscallArgs

type BindSyscallArgs struct {
	Addr *_Ctype_struct_sockaddr
	Sk   *_Ctype_struct_sock
}

type ClassificationProgram

type ClassificationProgram = uint32

const (
	ClassificationQueues ClassificationProgram = 0x2
	ClassificationDBs    ClassificationProgram = 0x3
	ClassificationGRPC   ClassificationProgram = 0x5
)

type Conn

type Conn struct {
	Tup             ConnTuple
	Conn_stats      ConnStats
	Tcp_stats       TCPStats
	Tcp_retransmits uint32
}

type ConnDirection

type ConnDirection uint8

const (
	Unknown  ConnDirection = 0x0
	Incoming ConnDirection = 0x1
	Outgoing ConnDirection = 0x2
)

type ConnFamily

type ConnFamily uint32

const (
	IPv4 ConnFamily = 0x0
	IPv6 ConnFamily = 0x2
)

func (ConnFamily) String

func (c ConnFamily) String() string

type ConnFlags

type ConnFlags uint32

const (
	LInit   ConnFlags = 0x1
	RInit   ConnFlags = 0x2
	Assured ConnFlags = 0x4
)

type ConnStats

type ConnStats struct {
	Sent_bytes     uint64
	Recv_bytes     uint64
	Sent_packets   uint32
	Recv_packets   uint32
	Timestamp      uint64
	Duration       uint64
	Cookie         uint32
	Protocol_stack ProtocolStack
	Flags          uint8
	Direction      uint8
	Pad_cgo_0      [6]byte
}

func (ConnStats) ConnectionDirection

func (cs ConnStats) ConnectionDirection() ConnDirection

ConnectionDirection returns the direction of the connection (incoming vs outgoing).

func (ConnStats) IsAssured

func (cs ConnStats) IsAssured() bool

IsAssured returns whether the connection has seen traffic in both directions.

type ConnTuple

type ConnTuple struct {
	Saddr_h  uint64
	Saddr_l  uint64
	Daddr_h  uint64
	Daddr_l  uint64
	Sport    uint16
	Dport    uint16
	Netns    uint32
	Pid      uint32
	Metadata uint32
}

func (ConnTuple) DestAddress

func (t ConnTuple) DestAddress() util.Address

DestAddress returns the destination address

func (ConnTuple) DestEndpoint

func (t ConnTuple) DestEndpoint() string

DestEndpoint returns the destination address and source port joined

func (ConnTuple) Family

func (t ConnTuple) Family() ConnFamily

Family returns whether a tuple is IPv4 or IPv6

func (ConnTuple) SourceAddress

func (t ConnTuple) SourceAddress() util.Address

SourceAddress returns the source address

func (ConnTuple) SourceEndpoint

func (t ConnTuple) SourceEndpoint() string

SourceEndpoint returns the source address and source port joined

func (ConnTuple) String

func (t ConnTuple) String() string

func (ConnTuple) Type

func (t ConnTuple) Type() ConnType

Type returns whether a tuple is TCP or UDP

type ConnType

type ConnType uint32

const (
	UDP ConnType = 0x0
	TCP ConnType = 0x1
)

func (ConnType) String

func (c ConnType) String() string

type ConntrackTelemetry

type ConntrackTelemetry struct {
	Registers uint64
}

type ConntrackTuple

type ConntrackTuple struct {
	Saddr_h  uint64
	Saddr_l  uint64
	Daddr_h  uint64
	Daddr_l  uint64
	Sport    uint16
	Dport    uint16
	Netns    uint32
	Metadata uint32
	X_pad    uint32
}

func (ConntrackTuple) DestAddress

func (t ConntrackTuple) DestAddress() util.Address

DestAddress returns the destination address

func (ConntrackTuple) DestEndpoint

func (t ConntrackTuple) DestEndpoint() string

DestEndpoint returns the destination address and source port joined

func (ConntrackTuple) Family

func (t ConntrackTuple) Family() ConnFamily

Family returns whether a tuple is IPv4 or IPv6

func (ConntrackTuple) SourceAddress

func (t ConntrackTuple) SourceAddress() util.Address

SourceAddress returns the source address

func (ConntrackTuple) SourceEndpoint

func (t ConntrackTuple) SourceEndpoint() string

SourceEndpoint returns the source address and source port joined

func (ConntrackTuple) String

func (t ConntrackTuple) String() string

func (ConntrackTuple) Type

func (t ConntrackTuple) Type() ConnType

Type returns whether a tuple is TCP or UDP

type PIDFD

type PIDFD struct {
	Pid uint32
	Fd  uint32
}

type PortBinding

type PortBinding struct {
	Netns     uint32
	Port      uint16
	Pad_cgo_0 [2]byte
}

type ProtocolStack

type ProtocolStack struct {
	Api         uint8
	Application uint8
	Encryption  uint8
	Flags       uint8
}

type ProtocolStackWrapper

type ProtocolStackWrapper struct {
	Stack   ProtocolStack
	Updated uint64
}

type TCPState

type TCPState uint8

const (
	Established TCPState = 0x1
	Close       TCPState = 0x7
)

type TCPStats

type TCPStats struct {
	Rtt               uint32
	Rtt_var           uint32
	State_transitions uint16
	Pad_cgo_0         [2]byte
}

type Telemetry

type Telemetry struct {
	Tcp_failed_connect  uint64
	Tcp_sent_miscounts  uint64
	Unbatched_tcp_close uint64
	Unbatched_udp_close uint64
	Udp_sends_processed uint64
	Udp_sends_missed    uint64
	Udp_dropped_conns   uint64
}

type UDPRecvSock

type UDPRecvSock struct {
	Sk  *_Ctype_struct_sock
	Msg *_Ctype_struct_msghdr
}