stats

Documentation

Overview

Package stats provides units for managing statistics of the filtering DNS server.

Index

• type Config
• type DiskConfig
• type Entry
• type Interface
• type Result
• type StatsCtx
  • func New(conf Config) (s *StatsCtx, err error)
  • func (s *StatsCtx) Close() (err error)
  • func (s *StatsCtx) Start()
  • func (s *StatsCtx) TopClientsIP(maxCount uint) (ips []netip.Addr)
  • func (s *StatsCtx) Update(e Entry)
  • func (s *StatsCtx) WriteDiskConfig(dc *DiskConfig)
• type StatsResp
• type TimeUnit
• type UnitIDGenFunc

Types

type Config

type Config struct {
	// UnitID is the function to generate the identifier for current unit.  If
	// nil, the default function is used, see newUnitID.
	UnitID UnitIDGenFunc

	// ConfigModified will be called each time the configuration changed via web
	// interface.
	ConfigModified func()

	// HTTPRegister is the function that registers handlers for the stats
	// endpoints.
	HTTPRegister aghhttp.RegisterFunc

	// Filename is the name of the database file.
	Filename string

	// LimitDays is the maximum number of days to collect statistics into the
	// current unit.
	LimitDays uint32
}

Config is the configuration structure for the statistics collecting.

type DiskConfig

type DiskConfig struct {
	// Interval is the number of days for which the statistics are collected
	// before flushing to the database.
	Interval uint32 `yaml:"statistics_interval"`
}

DiskConfig is the configuration structure that is stored in file.

type Entry

type Entry struct {
	// Clients is the client's primary ID.
	//
	// TODO(a.garipov): Make this a {net.IP, string} enum?
	Client string

	// Domain is the domain name requested.
	Domain string

	// Result is the result of processing the request.
	Result Result

	// Time is the duration of the request processing in milliseconds.
	Time uint32
}

Entry is a statistics data entry.

type Interface

type Interface interface {
	// Start begins the statistics collecting.
	Start()

	io.Closer

	// Update collects the incoming statistics data.
	Update(e Entry)

	// GetTopClientIP returns at most limit IP addresses corresponding to the
	// clients with the most number of requests.
	TopClientsIP(limit uint) []netip.Addr

	// WriteDiskConfig puts the Interface's configuration to the dc.
	WriteDiskConfig(dc *DiskConfig)
}

Interface is the statistics interface to be used by other packages.

type Result

type Result int

Result is the resulting code of processing the DNS request.

const (
	RNotFiltered Result = iota + 1
	RFiltered
	RSafeBrowsing
	RSafeSearch
	RParental
)

Supported Result values.

TODO(e.burkov): Think about better naming.

type StatsCtx

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

StatsCtx collects the statistics and flushes it to the database. Its default flushing interval is one hour.

TODO(e.burkov): Use atomic.Pointer for accessing db in go1.19.

func New

func New(conf Config) (s *StatsCtx, err error)

New creates s from conf and properly initializes it. Don't use s before calling it's Start method.

func (*StatsCtx) Close

func (s *StatsCtx) Close() (err error)

Close implements the io.Closer interface for *StatsCtx.

func (*StatsCtx) Start

func (s *StatsCtx) Start()

Start implements the Interface interface for *StatsCtx.

func (*StatsCtx) TopClientsIP

func (s *StatsCtx) TopClientsIP(maxCount uint) (ips []netip.Addr)

TopClientsIP implements the Interface interface for *StatsCtx.

func (*StatsCtx) Update

func (s *StatsCtx) Update(e Entry)

Update implements the Interface interface for *StatsCtx.

func (*StatsCtx) WriteDiskConfig

func (s *StatsCtx) WriteDiskConfig(dc *DiskConfig)

WriteDiskConfig implements the Interface interface for *StatsCtx.

type StatsResp

type StatsResp struct {
	TimeUnits string `json:"time_units"`

	TopQueried []topAddrs `json:"top_queried_domains"`
	TopClients []topAddrs `json:"top_clients"`
	TopBlocked []topAddrs `json:"top_blocked_domains"`

	DNSQueries []uint64 `json:"dns_queries"`

	BlockedFiltering     []uint64 `json:"blocked_filtering"`
	ReplacedSafebrowsing []uint64 `json:"replaced_safebrowsing"`
	ReplacedParental     []uint64 `json:"replaced_parental"`

	NumDNSQueries           uint64 `json:"num_dns_queries"`
	NumBlockedFiltering     uint64 `json:"num_blocked_filtering"`
	NumReplacedSafebrowsing uint64 `json:"num_replaced_safebrowsing"`
	NumReplacedSafesearch   uint64 `json:"num_replaced_safesearch"`
	NumReplacedParental     uint64 `json:"num_replaced_parental"`

	AvgProcessingTime float64 `json:"avg_processing_time"`
}

StatsResp is a response to the GET /control/stats.

type TimeUnit

type TimeUnit int

TimeUnit is the unit of measuring time while aggregating the statistics.

const (
	Hours TimeUnit = iota
	Days
)

Supported TimeUnit values.

type UnitIDGenFunc

type UnitIDGenFunc func() (id uint32)

UnitIDGenFunc is the signature of a function that generates a unique ID for the statistics unit.