stat

Documentation

Overview

Package stat provides time-bucketed statistics collection for UDP probe packets. It tracks per-bucket sent/received counts, loss rates, RTT, and bit-flip events, and periodically reports summary via a pluggable Sender.

Index

• func GetNextPorts(clientPort, serverPort uint16, clientPortRange, serverPortRange PortRange) (uint16, uint16)
• type LogSender
  • func NewLogSender(logger *log.Logger, verbose bool) *LogSender
  • func (s *LogSender) Send(r StatResult)
• type PortRange
• type Processor
  • func NewProcessor(span, delay time.Duration) *Processor
  • func (p *Processor) AddStat(s Stat)
  • func (p *Processor) Run(ctx context.Context)
• type Sender
• type Stat
  • func NewServerStat(clientAddr, serverAddr string, clientPortRange, serverPortRange PortRange, ...) Stat
  • func NewStat(clientAddr, serverAddr string, clientPortRange, serverPortRange PortRange, ...) Stat
• type StatResult

Functions

func GetNextPorts

func GetNextPorts(clientPort, serverPort uint16, clientPortRange, serverPortRange PortRange) (uint16, uint16)

GetNextPorts advances the port pair in odometer style: dstPort increments first; on wrap it resets and srcPort increments.

Types

type LogSender

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

LogSender implements Sender by writing stat results to a *log.Logger.

func NewLogSender

func NewLogSender(logger *log.Logger, verbose bool) *LogSender

NewLogSender creates a LogSender that writes to the given logger. When verbose is true, per-port loss details are included.

func (*LogSender) Send

func (s *LogSender) Send(r StatResult)

Send writes the StatResult to the logger. Loss-free buckets are logged at INFO level; buckets with loss are logged at WARN level with additional loss-port details when verbose is enabled.

type PortRange

type PortRange struct {
	Min int
	Max int
}

PortRange represents an inclusive range of UDP port numbers.

type Processor

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

Processor periodically calls statOnce on all registered Stat instances.

func NewProcessor

func NewProcessor(span, delay time.Duration) *Processor

NewProcessor creates a Processor that reports statistics every span, starting after an initial delay.

func (*Processor) AddStat

func (p *Processor) AddStat(s Stat)

AddStat registers a Stat instance for periodic reporting. Safe for concurrent use.

func (*Processor) Run

func (p *Processor) Run(ctx context.Context)

Run starts the periodic reporting loop. It waits for the configured delay, then reports all stats once per span tick. It stops when ctx is cancelled.

type Sender

type Sender interface {
	// Send is called once per time bucket with the aggregated statistics.
	Send(result StatResult)
}

Sender is the interface for consuming aggregated stat results. Implementations can write to logs, send to Kafka, push to ClickHouse, etc.

type Stat

type Stat interface {

	// Put records a sent probe packet.
	Put(clientPort, serverPort uint16, seq uint64, ts int64)
	// Delete removes a sent record (e.g. when the send itself failed).
	Delete(seq uint64, ts int64)
	// Received marks a probe packet as received and records its RTT.
	Received(seq uint64, ts, rtt int64, hasBitflip bool)
	// ReceivedRST marks a probe as responded with TCP RST (denied).
	// TCP SYN scanners use this to distinguish RST from SYN-ACK.
	ReceivedRST(seq uint64, ts, rtt int64)
	// ReceivedAndFix marks a probe as received and corrects the previous
	// bucket's sent count and starting ports using values from the client.
	ReceivedAndFix(seq uint64, ts, rtt int64, lastSentCount uint32, lastStartSrcPort, lastStartDstPort uint16, hasBitflip bool)
	// contains filtered or unexported methods
}

Stat is the interface for recording probe packet statistics. Implementations track sent, received, lost, and bit-flipped packets within time-bucketed windows.

func NewServerStat

func NewServerStat(clientAddr, serverAddr string, clientPortRange, serverPortRange PortRange,
	rateInSpan int64, span, delay time.Duration, sender Sender) Stat

NewServerStat creates a server-side Stat instance that tracks probe statistics for the given client-server pair. Results are sent via the provided Sender.

func NewStat

func NewStat(clientAddr, serverAddr string, clientPortRange, serverPortRange PortRange,
	rateInSpan int64, span, delay time.Duration, sender Sender) Stat

NewStat creates a Stat instance that tracks probe statistics between the given client and server address over the configured port ranges. Results are sent via the provided Sender.

type StatResult

type StatResult struct {
	Timestamp         time.Time
	ClientAddr        string
	ServerAddr        string
	ServerSide        bool
	Sent              int
	Received          int
	Loss              int
	LossRate          float64
	AvgRTT            int64
	MaxRTT            int64
	SynAckCount       int
	RSTCount          int
	LossPorts         map[int]int
	BitflipPorts      map[int]int
	LossPortsCount    map[string]int
	BitflipPortsCount map[string]int
}

StatResult holds the aggregated statistics for a single time bucket.