Documentation
¶
Overview ¶
Package coveragebus is the bus plane of the continuous-coverage stream (ADR-0169 §SD4): subjects, the codec seam, producer and consumer. It mirrors sysmetricsbus and stays free of runtime/coverage and decoder imports — the concrete sampler is wired in covscrape, so a consumer importing this package pulls in no acquisition code.
Index ¶
- Constants
- Variables
- func IntervalFromEnv() (interval time.Duration, enabled bool)
- func ParseInterval(raw string) (interval time.Duration, enabled bool)
- func SampleSubject(hostToken string) (subject string)
- func SampleSubjectWildcard() (subject string)
- type CBORCodec
- type Codec
- type Consumer
- type ConsumerOptions
- type Producer
- type ProducerOptions
- type UpdateSampler
Constants ¶
const ( MinInterval = 1 * time.Second MaxInterval = 10 * time.Minute )
MinInterval and MaxInterval clamp the producer's tick period. Coverage churn is slow and each tick serializes the process's counter arrays, so the floor sits well above the metric plane's.
const DefaultInterval = 5 * time.Second
DefaultInterval is the tick period when ProducerOptions.Interval is unset.
const ServiceAppId app.AppIdT = "runtime.coverage"
ServiceAppId is the bus identity of the coverage sampler service, mirroring "runtime.sysmetrics". It is the only identity that should hold the coverage publish capability.
const SubjectRoot = "coverage"
SubjectRoot is the top-level subject family of the coverage plane.
const SubjectWildcard = SubjectRoot + ".>"
SubjectWildcard matches every coverage subject; the cap pattern for the producer (publish) and consumers (subscribe).
Variables ¶
var Interval = env.NewString(env.Spec{ Name: "IMZERO2_COVERAGE_INTERVAL", Default: "5s", Description: "coverage sample interval on -cover -covermode=atomic builds (ADR-0169); a zero or negative duration disables sampling", Category: env.CategorySystem, })
Interval is the coverage sample cadence knob (ADR-0169 §SD4, registered per ADR-0009). The sampler only exists on -cover -covermode=atomic builds; on those, a zero or negative duration disables sampling.
Functions ¶
func IntervalFromEnv ¶
IntervalFromEnv reads and interprets the knob.
func ParseInterval ¶
ParseInterval interprets the knob's raw value: a non-positive duration disables sampling, an unparsable value falls back to the default (a misconfigured knob must not silently switch the lane off).
func SampleSubject ¶
SampleSubject returns the per-host update subject ("coverage.{host}.sample"). An empty token falls back to "local". Host tokens follow the metric plane's rule — callers pass sysmetricsbus.DefaultHostToken() or an equally sanitised token.
func SampleSubjectWildcard ¶
func SampleSubjectWildcard() (subject string)
SampleSubjectWildcard matches every host's update subject (coverage.*.sample).
Types ¶
type CBORCodec ¶
type CBORCodec struct{}
func NewCBORCodec ¶
func NewCBORCodec() (c CBORCodec)
type Codec ¶
type Codec interface {
Encode(upd *covsnap.Update) (payload []byte, err error)
Decode(payload []byte) (upd *covsnap.Update, err error)
}
Codec is the wire seam of the coverage plane, and CBORCodec is what it carries.
This followed sysmetricsbus, which shipped CBOR as an interim on the way to ADR-0090 §SD3's facts bus codec. That swap was since abandoned there (ADR-0184), so the precedent no longer carries a pending replacement — only the seam. What the coverage plane's wire should be is ADR-0169's to settle; nothing here is waiting on a decision made elsewhere. ADR-0089 keeps the bus wire distinct from the ingest wire either way.
type Consumer ¶
type Consumer struct {
// contains filtered or unexported fields
}
Consumer is the subscribing half of the coverage plane: it decodes each published update and hands it to Handler. The handler runs on whatever goroutine the bus dispatches on — under inprocbus that is the publisher's goroutine, synchronously — so it must not block.
func NewConsumer ¶
func NewConsumer(opts ConsumerOptions) (inst *Consumer, err error)
NewConsumer validates opts and returns a Consumer that is not yet subscribed; call Start to subscribe.
type ConsumerOptions ¶
type ConsumerOptions struct {
Bus app.BusI
Subject string
Codec Codec
Handler func(upd *covsnap.Update)
Log zerolog.Logger
}
ConsumerOptions configures NewConsumer. Bus, Subject, Codec, and Handler are required.
type Producer ¶
type Producer struct {
// contains filtered or unexported fields
}
Producer is the publishing half of the coverage plane (ADR-0169 §SD4): it owns the sampler, ticks at its configured cadence, encodes each update, and publishes it. Deltas ride fire-and-forget Publish; the sampler's periodic full re-statements are what heal a consumer that missed one.
func NewProducer ¶
func NewProducer(opts ProducerOptions) (inst *Producer, err error)
NewProducer validates opts and returns a stopped Producer; call Start to begin ticking.
type ProducerOptions ¶
type ProducerOptions struct {
Sampler UpdateSampler
Bus app.BusI
Subject string
Codec Codec
Interval time.Duration
Log zerolog.Logger
}
ProducerOptions configures NewProducer. Sampler, Bus, Subject, and Codec are required.
type UpdateSampler ¶
UpdateSampler is the producer's view of the coverage source: anything that folds one sample into a pre-aggregated update and can be closed. *coverage.Sampler satisfies it. The interface keeps this package free of runtime/coverage imports — the concrete sampler is wired in covscrape.
Source Files