capture

package
v4.1.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2025 License: GPL-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package capture is used to set up packet capturing and specifies the flow format. The API to interact with the capture manager is specified in a sub-package.

Index

Constants

View Source 
const (

	// MaxIfaces is the maximum number of interfaces we can monitor
	MaxIfaces = 1024
)

Variables

View Source 
var (
	// DefaultRotationDurationHistogramBins provides a reasonable standard set of histogram bins
	DefaultRotationDurationHistogramBins = []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 0.75, 1}
)
View Source 
var (

	// ErrLocalBufferOverflow signifies that the local packet buffer is full
	ErrLocalBufferOverflow = errors.New("local packet buffer overflow")
)

Functions

func ParsePacketV4 

func ParsePacketV4(ipLayer capture.IPLayer) (epHash capturetypes.EPHashV4, auxInfo byte, errno capturetypes.ParsingErrno)

ParsePacketV4 processes / extracts all information contained in the v6 IP layer received from a capture source and converts it to a hash and flags to be added to the flow map

func ParsePacketV6 

func ParsePacketV6(ipLayer capture.IPLayer) (epHash capturetypes.EPHashV6, auxInfo byte, errno capturetypes.ParsingErrno)

ParsePacketV6 processes / extracts all information contained in the v6 IP layer received from a capture source and converts it to a hash and flags to be added to the flow map

Types

type Capture 

type Capture struct {

	// Mutex to allow concurrent access to capture components
	// This is _unrelated_ to the three-point capture lock to
	// interrupt the capture for purposes of e.g. rotation
	sync.Mutex
	// contains filtered or unexported fields
}

Capture captures and logs flow data for all traffic on a given network interface. For each Capture, a goroutine is spawned at creation time. To avoid leaking this goroutine, be sure to call Close() when you're done with a Capture.

Each capture is associated with a network interface when created. This interface can never be changed.

All public methods of Capture are threadsafe.

func (*Capture) Iface 

func (c *Capture) Iface() string

Iface returns the name of the interface

func (*Capture) SetSourceInitFn 

func (c *Capture) SetSourceInitFn(fn sourceInitFn) *Capture

SetSourceInitFn sets a custom function used to initialize a new capture

type Flow 

type Flow types.Counters

Flow stores a goProbe flow (alias for types.Counters to allow for extension with flow specific methods)

func NewFlow 

func NewFlow(pktType capture.PacketType, pktTotalLen uint32) *Flow

NewFlow creates a new flow based on the packet

func (*Flow) Reset 

func (f *Flow) Reset()

Reset resets / null all counter values

func (*Flow) UpdateFlow 

func (f *Flow) UpdateFlow(pktType capture.PacketType, pktTotalLen uint32)

UpdateFlow increments flow counters if the packet belongs to an existing flow

type FlowInfo 

type FlowInfo struct {
	Idle                    bool                `json:"idle"`
	DirectionConfidenceHigh bool                `json:"direction_confidence_high"`
	Flow                    results.ExtendedRow `json:"flow"`
}

FlowInfo summarizes information about a given flow

type FlowInfos 

type FlowInfos []FlowInfo

FlowInfos is a list of FlowInfo objects

func (FlowInfos) TablePrint 

func (fs FlowInfos) TablePrint(w io.Writer) error

TablePrint prints the list of flow infos in a formatted table

type FlowLog 

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

FlowLog stores flows. It is NOT threadsafe.

func NewFlowLog 

func NewFlowLog() *FlowLog

NewFlowLog creates a new flow log for storing flows.

func (*FlowLog) Aggregate 

func (f *FlowLog) Aggregate() (agg *hashmap.AggFlowMap)

Aggregate extracts an AggFlowMap from the currently active flowMap. The flowMap itself is not modified in the process.

Returns an AggFlowMap containing all flows since the last call to Rotate.

func (*FlowLog) FlowsV4 

func (f *FlowLog) FlowsV4() map[string]*Flow

FlowsV4 provides an iterator for the internal flow map

func (*FlowLog) FlowsV6 

func (f *FlowLog) FlowsV6() map[string]*Flow

FlowsV6 provides an iterator for the internal flow map

func (*FlowLog) Len 

func (f *FlowLog) Len() int

Len returns the number of flows in the FlowLog

func (*FlowLog) MarshalJSON 

func (f *FlowLog) MarshalJSON() ([]byte, error)

MarshalJSON implements the jsoniter.Marshaler interface

func (*FlowLog) Rotate 

func (f *FlowLog) Rotate() (agg *hashmap.AggFlowMap, totals *types.Counters)

Rotate rotates the flow log. All flows are reset to no packets and traffic. Moreover, any flows not worth keeping (according to Flow.IsWorthKeeping) are discarded.

Returns an AggFlowMap containing all flows since the last call to Rotate.

type LocalBuffer 

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

LocalBuffer denotes a local packet buffer used to temporarily capture packets from the source (e.g. during rotation) to avoid a ring / kernel buffer overflow

func NewLocalBuffer 

func NewLocalBuffer(memPool *LocalBufferPool) *LocalBuffer

NewLocalBuffer initializes a new local buffer using a global memory pool and a maximum buffer size

func (*LocalBuffer) Add 

func (l *LocalBuffer) Add(epHash []byte, pktType byte, pktSize uint32, isIPv4 bool, auxInfo byte, errno capturetypes.ParsingErrno) (ok bool)

Add adds an element to the buffer, returning ok = true if successful If the buffer is full / may not grow any further, ok is false

func (*LocalBuffer) Assign 

func (l *LocalBuffer) Assign(data []byte)

Assign sets the actual underlying data slice (obtained from a memory pool) of this buffer

func (*LocalBuffer) Next 

func (l *LocalBuffer) Next() ([]byte, byte, uint32, bool, byte, capturetypes.ParsingErrno, bool)

Next fetches the i-th element from the buffer

func (*LocalBuffer) Reset 

func (l *LocalBuffer) Reset()

Reset resets the buffer position

func (*LocalBuffer) Usage 

func (l *LocalBuffer) Usage() float64

Usage return the relative fraction of the buffer capacity in use (i.e. written to, independent of number of items already retreived by Next())

type LocalBufferPool 

type LocalBufferPool struct {
	NBuffers      int
	MaxBufferSize int
	*concurrency.MemPoolLimitUnique
}

LocalBufferPool provides a wrapper around a MemPoolLimitUnique with a maximum size

func NewLocalBufferPool 

func NewLocalBufferPool(nBuffers, maxBufferSize int) *LocalBufferPool

NewLocalBufferPool initializes a new local buffer pool

type Manager 

type Manager struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Manager manages a set of Capture instances. Each interface can be associated with up to one Capture.

func InitManager 

func InitManager(ctx context.Context, config *config.Config, opts ...ManagerOption) (*Manager, error)

InitManager initializes a CaptureManager and the underlying writeout logic Used as primary entrypoint for the goProbe binary and E2E tests

func NewManager 

func NewManager(writeoutHandler writeout.Handler, opts ...ManagerOption) *Manager

NewManager creates a new CaptureManager

func (*Manager) Close 

func (cm *Manager) Close(ctx context.Context, ifaces ...string)

Close stops / closes all (or a set of) interfaces

func (*Manager) Config 

func (cm *Manager) Config(ifaces ...string) (ifaceConfigs config.Ifaces)

Config returns the runtime config of the capture manager for all (or a set of) interfaces

func (*Manager) GetFlowMaps 

func (cm *Manager) GetFlowMaps(ctx context.Context, filterFn goDB.FilterFn, writeoutChan chan<- hashmap.AggFlowMapWithMetadata, ifaces ...string)

GetFlowMaps extracts a copy of all active flows and sends them on the provided channel (compatible with normal query processing). This way, live data can be added to a query result

func (*Manager) GetTimestamps 

func (cm *Manager) GetTimestamps() (startedAt, lastRotation time.Time)

GetTimestamps is a combination of LastRotation() and StartedAt(). It exists to save a lock in case both timestamps are requested

func (*Manager) LastRotation 

func (cm *Manager) LastRotation() (t time.Time)

LastRotation returns the timestamp of the last DB writeout / rotation

func (*Manager) ScheduleWriteouts 

func (cm *Manager) ScheduleWriteouts(ctx context.Context, interval time.Duration)

ScheduleWriteouts creates a new goroutine that executes a DB writeout in defined time intervals

func (*Manager) StartedAt 

func (cm *Manager) StartedAt() (t time.Time)

StartedAt returns the timestamp when the capture manager was initialized

func (*Manager) Status 

func (cm *Manager) Status(ctx context.Context, ifaces ...string) (statusmap capturetypes.InterfaceStats)

Status fetches the current capture stats from all (or a set of) interfaces

func (*Manager) Update 

func (cm *Manager) Update(ctx context.Context, ifaces config.Ifaces) (enabled, updated, disabled capturetypes.IfaceChanges, err error)

Update the configuration for all (or a set of) interfaces

type ManagerOption 

type ManagerOption func(cm *Manager)

ManagerOption denotes a functional option for any CaptureManager

func WithLocalBuffers 

func WithLocalBuffers(nBuffers, sizeLimit int) ManagerOption

WithLocalBuffers sets one or multiple local buffers for the capture manager

func WithMetrics 

func WithMetrics(metrics *Metrics) ManagerOption

WithMetrics enables / sets tracking of metrics

func WithSkipWriteoutSchedule 

func WithSkipWriteoutSchedule(skip bool) ManagerOption

WithSkipWriteoutSchedule disables scheduled writeouts

func WithSourceInitFn 

func WithSourceInitFn(fn sourceInitFn) ManagerOption

WithSourceInitFn sets a custom function used to initialize a new capture

type Metrics 

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

Metrics denotes all capture-specific metrics, tracked in Prometheus

func NewMetrics 

func NewMetrics(opts ...MetricsOption) *Metrics

NewMetrics instantiates a new set of capture metrics

func (*Metrics) ObserveBytesTotal 

func (m *Metrics) ObserveBytesTotal(iface, direction string) prometheus.Counter

ObserveBytesTotal returns the counter metric relevant for the provided labels

func (*Metrics) ObserveCaptureIssues 

func (m *Metrics) ObserveCaptureIssues(iface, issueType string) prometheus.Counter

ObserveCaptureIssues returns the counter metric relevant for the provided labels

func (*Metrics) ObserveGlobalBufferUsage 

func (m *Metrics) ObserveGlobalBufferUsage(iface string) prometheus.Gauge

ObserveGlobalBufferUsage returns the gauge metric relevant for the provided labels

func (*Metrics) ObserveNumFlows 

func (m *Metrics) ObserveNumFlows(iface string) prometheus.Gauge

ObserveNumFlows returns the gauge metric relevant for the provided labels

func (*Metrics) ObserveNumIfacesCapturing 

func (m *Metrics) ObserveNumIfacesCapturing() prometheus.Gauge

ObserveNumIfacesCapturing returns the gauge metric

func (*Metrics) ObservePacketsDropped 

func (m *Metrics) ObservePacketsDropped(iface string) prometheus.Counter

ObservePacketsDropped returns the counter metric relevant for the provided labels

func (*Metrics) ObservePacketsProcessed 

func (m *Metrics) ObservePacketsProcessed(iface string) prometheus.Counter

ObservePacketsProcessed returns the counter metric relevant for the provided labels

func (*Metrics) ObservePacketsTotal 

func (m *Metrics) ObservePacketsTotal(iface, direction string) prometheus.Counter

ObservePacketsTotal returns the counter metric relevant for the provided labels

func (*Metrics) ObserveRotationDuration 

func (m *Metrics) ObserveRotationDuration() prometheus.Histogram

ObserveRotationDuration returns the histogram metric

func (*Metrics) ResetCountersTestingOnly 

func (m *Metrics) ResetCountersTestingOnly()

ResetCountersTestingOnly allows to externally reset all Prometheus counters (e.g. for testing purposes or in order to manually reset all of them) This method must not (and cannot) be called outside of testing

type MetricsOption 

type MetricsOption func(*Metrics)

MetricsOption denotes a functional option for Metrics

func DisableIfaceTracking 

func DisableIfaceTracking() MetricsOption

DisableIfaceTracking removes the "iface" label from all Prometheus metrics (reducing cardinality, in particular if many interfaces from many sensors are being tracked)

type RunGroup 

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

RunGroup wraps the common waitgroup setup for go routines that need to finish before continuing with instruction execution.

func (*RunGroup) Run 

func (rg *RunGroup) Run(f func())

Run executes any function inside a go routine and waits for it

func (*RunGroup) Wait 

func (rg *RunGroup) Wait()

Wait wraps the sync.Wait method

type Source 

type Source = capture.SourceZeroCopy

Source redefines any slimcap zero copy source interface type

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.