session

Documentation

Overview

Package session provides functions to track sessions with a throughput of data

Index

• type Collector
  • func NewCollector(config CollectorConfig) Collector
  • func NewNullCollector() Collector
• type CollectorConfig
• type Config
• type Peers
• type Registry
  • func New(conf Config) (Registry, error)
• type RegistryReader
• type Session
• type Stats
• type Summary

Types

type Collector

type Collector interface {
	// Register registers a new session. A session has to be activated in order
	// not to be dropped. A different id distinguishes different sessions.
	Register(id, reference, location, peer string)

	// Activate activates the session with the id. Returns true if the session
	// has been activated, false if the session was already activated.
	Activate(id string) bool

	// RegisterAndActivate registers and an activates a session.
	RegisterAndActivate(id, reference, location, peer string)

	// Add arbitrary extra data to a session
	Extra(id, extra string)

	// Unregister cancels a session prematurely.
	Unregister(id string)

	// Ingress adds size bytes of ingress traffic to a session.
	Ingress(id string, size int64)

	// Egress adds size bytes of egress traffic to a session.
	Egress(id string, size int64)

	// IngressBitrate returns the current bitrate of ingress traffic.
	IngressBitrate() float64

	// EgressBitrate returns the current bitrate of egress traffic.
	EgressBitrate() float64

	// MaxIngressBitrate return the defined maximum ingress bitrate. All values <= 0
	// mean no limit.
	MaxIngressBitrate() float64

	// MaxEgressBitrate return the defined maximum egress bitrate. All values <= 0
	// mean no limit.
	MaxEgressBitrate() float64

	// TopIngressBitrate returns the summed current top bitrates of all ingress sessions.
	TopIngressBitrate() float64

	// TopEgressBitrate returns the summed current top bitrates of all egress sessions.
	TopEgressBitrate() float64

	// IsIngressBitrateExceeded returns whether the defined maximum ingress bitrate has
	// been exceeded.
	IsIngressBitrateExceeded() bool

	// IsEgressBitrateExceeded returns whether the defined maximum egress bitrate has
	// been exceeded.
	IsEgressBitrateExceeded() bool

	// IsSessionsExceeded return whether the maximum number of session have been exceeded.
	IsSessionsExceeded() bool

	// IsKnowsession returns whether a session with the given id exists.
	IsKnownSession(id string) bool

	// IsAllowedIP returns whether traffic from/to the given IP should be considered.
	IsCollectableIP(ip string) bool

	// Summary returns the summary of all currently active sessions and the session history.
	Summary() Summary

	// Active returns a list of currently active sessions.
	Active() []Session

	// SessionIngressTopBitrate returns the top ingress bitrate of a specific session.
	SessionTopIngressBitrate(id string) float64

	// SessionIngressTopBitrate returns the top egress bitrate of a specific session.
	SessionTopEgressBitrate(id string) float64

	// SessionSetIngressTopBitrate sets the current top ingress bitrate of a session.
	SessionSetTopIngressBitrate(id string, bitrate float64)

	// SessionSetEgressTopBitrate sets the current top egress bitrate of a session.
	SessionSetTopEgressBitrate(id string, bitrate float64)

	// Sessions returns the number of currently active sessions.
	Sessions() uint64

	AddCompanion(collector Collector)

	// IngressBitrate returns the current bitrate of ingress traffic.
	CompanionIngressBitrate() float64

	// EgressBitrate returns the current bitrate of egress traffic.
	CompanionEgressBitrate() float64

	// TopIngressBitrate returns the summed current top bitrates of all ingress sessions.
	CompanionTopIngressBitrate() float64

	// TopEgressBitrate returns the summed current top bitrates of all egress sessions.
	CompanionTopEgressBitrate() float64

	// Stop stops the collector to calculate rates
	Stop()
}

The Collector interface

func NewCollector

func NewCollector(config CollectorConfig) Collector

NewCollector returns a new collector according to the provided configuration. If such a collector can't be created, a NullCollector is returned.

func NewNullCollector

func NewNullCollector() Collector

NewNullCollector returns an implementation of the Collector interface that doesn't collect any metrics at all.

type CollectorConfig

type CollectorConfig struct {
	// MaxRxBitrate is the maximum ingress bitrate. It is used to query whether
	// the maximum bitrate is reached, based on the actucal bitrate.
	MaxRxBitrate uint64

	// MaxTxBitrate is the maximum egress bitrate. It is used to query whether
	// the maximum bitrate is reached, based on the actucal bitrate.
	MaxTxBitrate uint64

	// MaxSessions is the maximum number of session. It is used to query whether
	// the maximum number of sessions is reached, based on the actual number
	// of pending and active sessions.
	MaxSessions uint64

	// Limiter is an IPLimiter. It is used to query whether a session for an IP
	// should be created.
	Limiter net.IPLimiter

	// InactiveTimeout is the duration of how long a not yet activated session is kept.
	// A session gets activated with the first ingress or egress bytes.
	InactiveTimeout time.Duration

	// SessionTimeout is the duration of how long an idle active session is kept. A
	// session is idle if there are no ingress or egress bytes.
	SessionTimeout time.Duration

	// PersistInterval is the duration between persisting the
	// history. Can be 0. Then the history will only be persisted
	// at stopping the collector.
	PersistInterval time.Duration
}

CollectorConfig is the configuration for registering a new collector

type Config

type Config struct {
	// PersistFS is a filesystem in whose root the session history will be persisted. If it is nil, the
	// history will not be persisted.
	PersistFS fs.Filesystem

	// Logger is an instance of a logger. If it is nil, no logs
	// will be written.
	Logger log.Logger
}

Config is the configuration for creating a new registry

type Peers

type Peers struct {
	Stats

	Locations map[string]Stats
}

Peers is a group of the same peer grouped of the locations.

type Registry

type Registry interface {
	// Register returns a new collector from conf and registers it under the id and error is nil. In case of error
	// the returned collector is nil and the error is not nil.
	Register(id string, conf CollectorConfig) (Collector, error)

	// Unregister unregisters the collector with the ID, returns error if the ID is not registered
	Unregister(id string) error

	// UnregisterAll unregisters al registered collectors
	UnregisterAll()

	RegistryReader
}

The Registry interface

func New

func New(conf Config) (Registry, error)

New returns a new registry for collectors that implement the Registry interface. The error is non-nil if the PersistDir from the config can't be created.

type RegistryReader

type RegistryReader interface {
	// Collectors returns an array of all registered IDs
	Collectors() []string

	// Collector returns the collector with the ID, or nil if the ID is not registered
	Collector(id string) Collector

	// Summary returns the summary from a collector with the ID, or an empty summary if the ID is not registered
	Summary(id string) Summary

	// Active returns the active sessions from a collector with the ID, or an empty list if the ID is not registered
	Active(id string) []Session
}

type Session

type Session struct {
	ID           string
	Reference    string
	CreatedAt    time.Time
	Location     string
	Peer         string
	Extra        string
	RxBytes      uint64
	RxBitrate    float64 // bit/s
	TopRxBitrate float64 // bit/s
	TxBytes      uint64
	TxBitrate    float64 // bit/s
	TopTxBitrate float64 // bit/s
}

Session represents an active session

type Stats

type Stats struct {
	TotalSessions uint64
	TotalRxBytes  uint64
	TotalTxBytes  uint64
}

Stats holds the basic accumulated values like the number of sessions, total transmitted and received bytes.

type Summary

type Summary struct {
	MaxSessions  uint64
	MaxRxBitrate float64 // bit/s
	MaxTxBitrate float64 // bit/s

	CurrentSessions  uint64
	CurrentRxBitrate float64 // bit/s
	CurrentTxBitrate float64 // bit/s

	Active []Session

	Summary struct {
		Peers      map[string]Peers
		Locations  map[string]Stats
		References map[string]Stats
		Stats
	}
}

Summary is a summary over all current and past sessions. The past sessions are grouped over the Peers/Locations and the Locations.