metrics

Documentation

Overview

Package metrics provides tracking and exposure of Watchtower scan metrics. It integrates with Prometheus to monitor container scan outcomes.

Key components:

• Metrics: Handles metric queuing and updates.
• NewMetric: Creates metrics from scan reports.

Usage example:

// log is the process *zerolog.Logger supplied by the composition root.
m := metrics.Default()
m.RegisterScan(metrics.NewMetric(report))
if !m.QueueIsEmpty() {
    log.Info().Msg("Metrics queued")
}

The package uses Prometheus for metrics exposure and integrates with types.Report.

Index

• type HistoryEntry
• type Metric
  • func NewMetric(report types.Report) *Metric
• type Metrics
  • func Default() *Metrics
  • func NewWithRegistry(registry prometheus.Registerer) (*Metrics, error)
  • func (m *Metrics) GetHistory(since, until *time.Time, limit int) []HistoryEntry
  • func (m *Metrics) GetLastScan() *Metric
  • func (m *Metrics) HandleUpdate()
  • func (m *Metrics) QueueIsEmpty() bool
  • func (m *Metrics) RecordHistory(metric *Metric)
  • func (m *Metrics) Register(metric *Metric)
  • func (m *Metrics) RegisterScan(metric *Metric)
  • func (m *Metrics) Shutdown()

Types

type HistoryEntry

type HistoryEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Scanned   int       `json:"scanned"`
	Updated   int       `json:"updated"`
	Failed    int       `json:"failed"`
	Restarted int       `json:"restarted"`
	Skipped   int       `json:"skipped"`
}

HistoryEntry represents a single scan record in the history ring buffer.

type Metric

type Metric struct {
	Scanned   int `json:"scanned"`
	Updated   int `json:"updated"`
	Failed    int `json:"failed"`
	Restarted int `json:"restarted"`
	Skipped   int `json:"skipped"`
}

Metric holds data points from a Watchtower scan.

func NewMetric

func NewMetric(report types.Report) *Metric

NewMetric creates a Metric from a scan report.

Parameters:

• report: Scan report from types.Report.

Returns:

• *Metric: New metric instance.

type Metrics

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

Metrics handles processing and exposing scan metrics.

func Default

func Default() *Metrics

Default initializes or returns the singleton Metrics handler. It panics on registration failure, such as duplicate registration against the default registry.

Returns:

• *Metrics: Metrics handler with Prometheus metrics and goroutine.

func NewWithRegistry

func NewWithRegistry(registry prometheus.Registerer) (*Metrics, error)

NewWithRegistry creates a new Metrics handler with a custom Prometheus registry.

Parameters:

• registry: Prometheus registerer to use for metric registration.

Returns:

• (*Metrics, error): Metrics handler with Prometheus metrics and goroutine, or an error if registration fails.

func (*Metrics) GetHistory

func (m *Metrics) GetHistory(since, until *time.Time, limit int) []HistoryEntry

GetHistory returns a copy of the history entries, optionally filtered by since/until timestamps and limited to the most recent N entries. The returned slice is sorted by timestamp in ascending order.

func (*Metrics) GetLastScan

func (m *Metrics) GetLastScan() *Metric

GetLastScan returns a copy of the most recent scan metric, or nil if no scan has completed yet. The returned copy is safe to modify by the caller without affecting the internal metrics state.

Returns:

• *Metric: Copy of the last scan metric, or nil.

func (*Metrics) HandleUpdate

func (m *Metrics) HandleUpdate()

HandleUpdate processes metrics from the channel.

func (*Metrics) QueueIsEmpty

func (m *Metrics) QueueIsEmpty() bool

QueueIsEmpty checks if the metrics channel is empty.

Returns:

• bool: True if empty, false otherwise.

func (*Metrics) RecordHistory

func (m *Metrics) RecordHistory(metric *Metric)

RecordHistory stores a scan result in the ring buffer. When the buffer is full, the oldest entry is overwritten.

func (*Metrics) Register

func (m *Metrics) Register(metric *Metric)

Register attempts to enqueue a metric for processing. If the channel is full, the metric is dropped and the dropped counter is incremented.

Parameters:

• metric: Metric to register.

func (*Metrics) RegisterScan

func (m *Metrics) RegisterScan(metric *Metric)

RegisterScan enqueues a scan metric using the default handler.

Parameters:

• metric: Metric to register.

func (*Metrics) Shutdown

func (m *Metrics) Shutdown()

Shutdown gracefully stops the metrics processing goroutine. It closes the stopCh channel and cancels the context to signal the goroutine to exit. This method is idempotent and can be called multiple times safely.