trafficusage

Documentation

Overview

Package trafficusage implements the `traffic-usage` system plugin: eBPF TCX per-(port,protocol) and (opt-in) per-IP byte accounting on operator-selected interfaces, exported as Prometheus metrics and viewable via `show traffic-usage`.

The eBPF programs are assembled in pure Go (github.com/cilium/ebpf asm.Instructions) and loaded from memory: there is no C source, no committed object file, and no clang/LLVM build step. This deliberately diverges from the l2tp XDP-policing plugin, which commits bpf2go .o files. The cost is that the BPF logic is hand-written assembly with no compiler, so BPF_PROG_TEST_RUN per-path tests are load-bearing. See plan/spec-traffic-usage.md.

The plugin never drops or modifies traffic; it only counts bytes. IPv4 only, matching the upstream lan-bandwidth-exporter it is ported from.

Index

• Constants
• func BindMetrics(reg metrics.Registry)
• type Config
  • func ParseConfig(data string) (*Config, error)
  • func (c *Config) IsEmpty() bool
  • func (c *Config) Validate() error
• type InterfaceConfig
• type Monitor
  • func (m *Monitor) Reconcile(cfg *Config) error
  • func (m *Monitor) Snapshot() []counts
  • func (m *Monitor) Start()
  • func (m *Monitor) Stop()

Constants

const Name = "traffic-usage"

Name is the registered plugin name (hyphen form). The Go package is trafficusage.

Functions

func BindMetrics

func BindMetrics(reg metrics.Registry)

BindMetrics registers the ze_traffic_usage_* families on the registry. It is idempotent: registration by name returns the existing vector, so a config reload may call it again safely. A nil registry is a no-op.

Types

type Config

type Config struct {
	Enabled      bool
	Interval     time.Duration
	TrackIP      bool
	StaleTimeout time.Duration
	MaxEntries   uint32
	Interfaces   []InterfaceConfig
}

Config is the parsed traffic-usage configuration. Interval is global (a single poll loop). TrackIP, StaleTimeout, and MaxEntries here are the global defaults; each interface inherits them unless it sets its own override (resolved into InterfaceConfig at parse time).

func ParseConfig

func ParseConfig(data string) (*Config, error)

ParseConfig parses the traffic-usage JSON config section. The daemon delivers leaves as JSON strings ("2000"); array-form and unit-test configs embed JSON numbers and bools. Defaults are applied for absent leaves.

func (*Config) IsEmpty

func (c *Config) IsEmpty() bool

IsEmpty reports whether the config requests no accounting: the plugin is disabled. A reload that removes or disables the section parses to an empty Config and the engine tears down any running monitor.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the config for operability. An enabled section with no (enabled) interface or an out-of-range interval is rejected, as is any interface whose name is invalid, whose effective stale-timeout is a non-zero sub-second value, or whose effective max-entries is zero.

type InterfaceConfig

type InterfaceConfig struct {
	Name         string
	TrackIP      bool
	StaleTimeout time.Duration
	MaxEntries   uint32
}

InterfaceConfig is one accounted interface with its effective (override or inherited-global) settings already resolved.

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor orchestrates per-interface eBPF attachments and (from Phase 5) the metrics poller. It is platform-neutral: all kernel interaction is behind the attacher interface.

func (*Monitor) Reconcile

func (m *Monitor) Reconcile(cfg *Config) error

Reconcile records a new configuration and immediately drives the attached set toward it, resolving each configured interface to an ifindex. It is idempotent and degrades gracefully -- an interface that cannot be resolved or attached is logged and skipped, leaving the others unaffected (AC-12).

func (*Monitor) Snapshot

func (m *Monitor) Snapshot() []counts

Snapshot reads the current counters for every attached interface. Used by the `show traffic-usage` handler.

func (*Monitor) Start

func (m *Monitor) Start()

Start launches the metrics poller. It is idempotent.

func (*Monitor) Stop

func (m *Monitor) Stop()

Stop halts the poller, detaches every interface, and releases all resources.