Documentation
¶
Overview ¶
Package attribution holds the per-audit-route bookkeeping the attribution pipeline shares across its two halves: the audit ingress that PUBLISHES facts and the watch resolver that READS them.
It exists as its own package because the two halves live in packages that do not import each other (internal/webhook and internal/watch) and the control plane reads the same state from a third (internal/controller). One registry, three readers.
Index ¶
- Constants
- type RouteHealth
- func (h *RouteHealth) AuditDelivered() bool
- func (h *RouteHealth) FirstFactAt(route string) (time.Time, bool)
- func (h *RouteHealth) FirstFactEvents() <-chan event.GenericEvent
- func (h *RouteHealth) ObserveResolution(route string, factMatched bool) (bool, int)
- func (h *RouteHealth) RecordAuditDelivery()
- func (h *RouteHealth) RecordFactPublished(route string) bool
- func (h *RouteHealth) RecordPublishFailure()
- func (h *RouteHealth) TransportFailing() bool
- func (h *RouteHealth) TransportName() string
Constants ¶
const UnresolvedWarnThreshold = 5
UnresolvedWarnThreshold is how many consecutive unresolved events one audit route may produce, having never resolved a single one, before the resolver says so in the log. It is not 1 because a lone miss is ordinary: an audit batch can arrive after the grace window under load. A run of them with nothing ever matched is the signature of a route nobody writes to.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type RouteHealth ¶
type RouteHealth struct {
// Transport names the fact transport this operator was built with ("redis" or "memory"), for
// the message a provider shows while publishes are failing: the two fail for entirely different
// reasons and send the reader to different places. Set once at construction and read-only
// after; empty is fine and yields transport-neutral wording.
Transport string
// contains filtered or unexported fields
}
RouteHealth tracks, per audit route, whether a fact has ever been PUBLISHED on it, and — on the read side — whether attribution has ever resolved and how many events have gone unresolved since.
It makes one specific misconfiguration visible: a ClusterProvider whose spec.attribution.auditRoute names a route no API server posts under reads a partition nothing writes, so every commit through it is authored "attribution unresolved" with no error, no failed reconcile, and perfect mirroring. The published-fact half is what the ClusterProvider's AuditFactsReceived condition latches on; the resolve half is the log warning.
The zero value is ready to use. Every method is safe on a nil receiver, so a caller wired for configured-author mode (no attribution at all) needs no nil checks of its own.
func (*RouteHealth) AuditDelivered ¶
func (h *RouteHealth) AuditDelivered() bool
AuditDelivered reports whether any audit request has ever reached this operator in this process.
func (*RouteHealth) FirstFactAt ¶
func (h *RouteHealth) FirstFactAt(route string) (time.Time, bool)
FirstFactAt returns when the first fact was published on this route, and whether one ever was.
It answers only for THIS process: the registry is in-process state and a restart empties it, including under the memory transport. That is why the condition it feeds is latched in the object's persisted status rather than recomputed from here — see the ClusterProvider controller.
func (*RouteHealth) FirstFactEvents ¶
func (h *RouteHealth) FirstFactEvents() <-chan event.GenericEvent
FirstFactEvents returns the channel a controller wires via source.Channel so a route's first fact enqueues the ClusterProviders that read it. It is lazily created, so a zero-value registry and a wired one behave the same.
func (*RouteHealth) ObserveResolution ¶
func (h *RouteHealth) ObserveResolution(route string, factMatched bool) (bool, int)
ObserveResolution records one resolution outcome for a route and reports whether this is the moment to warn, plus the current unresolved run length. It warns at most once per route per process: the condition is a configuration mistake, so repeating it every event would bury the log without telling anyone anything new.
factMatched is "did a fact for this event exist on this route", NOT "did we name an author". The warning this feeds says the route has never carried a fact at all, so a fact that matched and named nobody still answers it: the route is demonstrably alive and the missing author is a different problem with a different fix.
The caller MUST act on the returned bool. Reaching the threshold latches warned[route], so a dropped true silences the route's warning for the life of the process.
func (*RouteHealth) RecordAuditDelivery ¶
func (h *RouteHealth) RecordAuditDelivery()
RecordAuditDelivery notes that an audit request carrying events reached this operator. It says nothing about routes: the apiserver posting anywhere is what it establishes, which is the difference between "nobody is sending us audit" and "your route is not the one being sent".
func (*RouteHealth) RecordFactPublished ¶
func (h *RouteHealth) RecordFactPublished(route string) bool
RecordFactPublished notes that a fact was published on this route and reports whether this was the FIRST one this process has seen for it. The first one also emits a reconcile notification.
It is called from the audit ingress after a batch has actually appended, so it means "a fact reached the transport", not "an audit event arrived": an event that names nobody publishes nothing and is not evidence that the route is wired end to end.
func (*RouteHealth) RecordPublishFailure ¶
func (h *RouteHealth) RecordPublishFailure()
RecordPublishFailure notes that an append to the fact transport failed. It is cleared by the next successful publish, so the flag tracks the CURRENT state rather than accumulating history.
It can read stale-failing for as long as no further batch is attempted, because only an attempt can observe a recovery. In practice that window is short: a failed publish returns an error to the API server, which retries the same batch.
func (*RouteHealth) TransportFailing ¶
func (h *RouteHealth) TransportFailing() bool
TransportFailing reports whether the last observed append to the fact transport failed. While true, nothing can be concluded about any route's configuration: every route looks silent.
func (*RouteHealth) TransportName ¶
func (h *RouteHealth) TransportName() string
TransportName returns the configured fact transport's name, or "" when it was not set.
Source Files