stats

Documentation

Overview

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

Index

• type Config
• 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) ShouldCount(host string, _, _ uint16, ids []string) bool
  • func (s *StatsCtx) Start()
  • func (s *StatsCtx) TopClientsIP(maxCount uint) (ips []netip.Addr)
  • func (s *StatsCtx) Update(e *Entry)
  • func (s *StatsCtx) WriteDiskConfig(dc *Config)
• type StatsResp
• type UnitIDGenFunc

Types

type Config

type Config struct {
	// Logger is used for logging the operation of the statistics management.
	// It must not be nil.
	Logger *slog.Logger

	// 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()

	// ShouldCountClient returns client's ignore setting.
	ShouldCountClient func([]string) bool

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

	// Ignored contains the list of host names, which should not be counted,
	// and matches them.
	Ignored *aghnet.IgnoreEngine

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

	// Limit is an upper limit for collecting statistics.
	Limit time.Duration

	// Enabled tells if the statistics are enabled.
	Enabled bool
}

Config is the configuration structure for the statistics collecting.

Do not alter any fields of this structure after using it.

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

	// Upstream is the upstream DNS server.
	Upstream string

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

	// ProcessingTime is the duration of the request processing from the start
	// of the request including timeouts.
	ProcessingTime time.Duration

	// UpstreamTime is the duration of the successful request to the upstream.
	UpstreamTime time.Duration
}

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 *Config)

	// ShouldCount returns true if request for the host should be counted.
	ShouldCount(host string, qType, qClass uint16, ids []string) bool
}

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.

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) ShouldCount

func (s *StatsCtx) ShouldCount(host string, _, _ uint16, ids []string) bool

ShouldCount returns true if request for the host should be counted.

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. e must not be nil.

func (*StatsCtx) WriteDiskConfig

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

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"`

	TopUpstreamsResponses []topAddrs      `json:"top_upstreams_responses"`
	TopUpstreamsAvgTime   []topAddrsFloat `json:"top_upstreams_avg_time"`

	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 UnitIDGenFunc

type UnitIDGenFunc func() (id uint32)

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