metrics

Documentation

Overview

Package metrics exposes dependency-free Prometheus text metrics for shunt.

Index

• type ActiveBatchState
• type ActiveBatchStateJSON
• type Collector
  • func New() *Collector
  • func (c *Collector) ForgetQueue(labels Labels)
  • func (c *Collector) Handler() http.Handler
  • func (c *Collector) IncBatchesStarted(labels Labels)
  • func (c *Collector) IncBounce(labels Labels)
  • func (c *Collector) IncGateOutcome(labels Labels, outcome string)
  • func (c *Collector) IncPRMerge(labels Labels)
  • func (c *Collector) IncReconcileError(labels Labels)
  • func (c *Collector) IncStagingConflict(labels Labels)
  • func (c *Collector) ObserveGateDuration(labels Labels, outcome string, d time.Duration)
  • func (c *Collector) ObserveLingerDuration(labels Labels, d time.Duration)
  • func (c *Collector) ObserveNativeMergeDuration(labels Labels, d time.Duration)
  • func (c *Collector) ObserveQueue(labels Labels, depth int, active bool)
  • func (c *Collector) ObserveQueueAge(labels Labels, oldest time.Duration)
  • func (c *Collector) ObserveQueueStatus(labels Labels, pending [][]int, active []ActiveBatchState, ...)
  • func (c *Collector) ObserveReconcileDuration(labels Labels, d time.Duration)
  • func (c *Collector) ObserveTimeInQueue(labels Labels, outcome string, age time.Duration)
  • func (c *Collector) StatusHandler() http.Handler
  • func (c *Collector) StatusPageHandler() http.Handler
  • func (c *Collector) StatusSnapshot() StatusSnapshot
  • func (c *Collector) WritePrometheus(w io.Writer)
• type EffectiveConfig
• type EffectiveConfigJSON
• type Labels
• type QueueStatus
• type StatusSnapshot

Types

type ActiveBatchState

type ActiveBatchState struct {
	PRs        []int
	Phase      string    // "waiting_gate", "waiting_merge", or "bisecting"
	PhaseSince time.Time // when the current phase started
}

ActiveBatchState is the observable state of one active (staged) batch.

type ActiveBatchStateJSON

type ActiveBatchStateJSON struct {
	PRs        []int  `json:"prs"`
	Phase      string `json:"phase"`
	PhaseSince string `json:"phase_since"` // RFC3339
}

ActiveBatchStateJSON is the per-batch phase detail included in QueueStatus.

type Collector

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

Collector stores process-local metrics and renders Prometheus text exposition.

func New

func New() *Collector

New returns an empty metrics collector.

func (*Collector) ForgetQueue

func (c *Collector) ForgetQueue(labels Labels)

ForgetQueue removes metrics for a queue that is no longer managed.

func (*Collector) Handler

func (c *Collector) Handler() http.Handler

Handler returns an HTTP handler for the Prometheus text endpoint.

func (*Collector) IncBatchesStarted

func (c *Collector) IncBatchesStarted(labels Labels)

IncBatchesStarted records a batch that was staged and sent to the gate.

func (*Collector) IncBounce

func (c *Collector) IncBounce(labels Labels)

IncBounce records a PR bounced from the queue.

func (*Collector) IncGateOutcome

func (c *Collector) IncGateOutcome(labels Labels, outcome string)

IncGateOutcome records a terminal gate result for a staging batch.

func (*Collector) IncPRMerge

func (c *Collector) IncPRMerge(labels Labels)

IncPRMerge records a PR landed through shunt's queue.

func (*Collector) IncReconcileError

func (c *Collector) IncReconcileError(labels Labels)

IncReconcileError records a reconcile loop error.

func (*Collector) IncStagingConflict

func (c *Collector) IncStagingConflict(labels Labels)

IncStagingConflict records a staging merge conflict.

func (*Collector) ObserveGateDuration

func (c *Collector) ObserveGateDuration(labels Labels, outcome string, d time.Duration)

ObserveGateDuration records how long a staged batch ran under gate test before reaching a terminal outcome. Labels the observation by outcome for alignment with shunt_gate_outcomes_total.

func (*Collector) ObserveLingerDuration

func (c *Collector) ObserveLingerDuration(labels Labels, d time.Duration)

ObserveLingerDuration records the duration a queue spent in the batch-linger window before forming a batch. Only called when linger was actually active.

func (*Collector) ObserveNativeMergeDuration

func (c *Collector) ObserveNativeMergeDuration(labels Labels, d time.Duration)

ObserveNativeMergeDuration records the time from when shunt released a PR to the forge's scheduled auto-merge worker until that PR was observed merged.

func (*Collector) ObserveQueue

func (c *Collector) ObserveQueue(labels Labels, depth int, active bool)

ObserveQueue records the current in-memory queue state.

func (*Collector) ObserveQueueAge

func (c *Collector) ObserveQueueAge(labels Labels, oldest time.Duration)

ObserveQueueAge records the oldest process-local age among currently queued PRs.

func (*Collector) ObserveQueueStatus

func (c *Collector) ObserveQueueStatus(labels Labels, pending [][]int, active []ActiveBatchState, lingerSince time.Time, cfg *EffectiveConfig)

ObserveQueueStatus records the current in-memory queue batches with phase detail. pending is the list of PR-number candidates waiting to be staged. active carries per-batch phase detail including phase and phase start time. lingerSince is non-zero when the queue is in the batch-linger window. cfg is the safe resolved configuration for this queue (may be nil on first call).

func (*Collector) ObserveReconcileDuration

func (c *Collector) ObserveReconcileDuration(labels Labels, d time.Duration)

ObserveReconcileDuration records the wall-clock time spent in one Reconcile call for this queue.

func (*Collector) ObserveTimeInQueue

func (c *Collector) ObserveTimeInQueue(labels Labels, outcome string, age time.Duration)

ObserveTimeInQueue records how long a PR spent in the process-local queue.

func (*Collector) StatusHandler

func (c *Collector) StatusHandler() http.Handler

StatusHandler returns an HTTP handler for the JSON queue status endpoint.

func (*Collector) StatusPageHandler

func (c *Collector) StatusPageHandler() http.Handler

StatusPageHandler returns a small human-readable queue status page.

func (*Collector) StatusSnapshot

func (c *Collector) StatusSnapshot() StatusSnapshot

StatusSnapshot returns a safe, machine-readable snapshot of queue state.

func (*Collector) WritePrometheus

func (c *Collector) WritePrometheus(w io.Writer)

WritePrometheus writes a full Prometheus text-format snapshot.

type EffectiveConfig

type EffectiveConfig struct {
	ConfigSource string // "repo" (.shunt.yml present) or "default"
	Base         string
	MergeStyle   string
	MaxBatch     int
	BatchLinger  time.Duration
	BatchTarget  int
	BisectFanout int
}

EffectiveConfig is the safe, resolved subset of per-queue configuration. Sensitive fields (token, bot email, instance URL, webhook secret) are intentionally excluded.

type EffectiveConfigJSON

type EffectiveConfigJSON struct {
	ConfigSource string `json:"config_source"` // "repo" or "default"
	Base         string `json:"base"`
	MergeStyle   string `json:"merge_style"`
	MaxBatch     int    `json:"max_batch"`
	BatchLinger  string `json:"batch_linger"` // Go duration string, e.g. "30s"
	BatchTarget  int    `json:"batch_target"`
	BisectFanout int    `json:"bisect_fanout"`
}

EffectiveConfigJSON is the safe, resolved queue configuration included in QueueStatus. Sensitive fields (token, bot email, instance URL, webhook secret) are excluded.

type Labels

type Labels struct {
	Owner string
	Repo  string
	Base  string
}

Labels identify one managed merge queue.

type QueueStatus

type QueueStatus struct {
	Owner          string  `json:"owner"`
	Repo           string  `json:"repo"`
	Base           string  `json:"base"`
	QueueDepth     int     `json:"queue_depth"`
	ActiveBatch    bool    `json:"active_batch"`
	ActiveBatches  [][]int `json:"active_batches"`
	PendingBatches [][]int `json:"pending_batches"`
	// New additive fields. Consumers relying only on the fields above are unaffected.
	ActiveBatchStates []ActiveBatchStateJSON `json:"active_batch_states,omitempty"`
	LingerSince       *string                `json:"linger_since,omitempty"` // RFC3339 while lingering
	Config            *EffectiveConfigJSON   `json:"config,omitempty"`
}

type StatusSnapshot

type StatusSnapshot struct {
	Queues []QueueStatus `json:"queues"`
}