Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeCounters(data []byte) (snap *covsnap.CounterSnapshot, err error)
- func DecodeMeta(data []byte) (prof *covsnap.MetaProfile, err error)
- func ProbeRuntimeSupport() (err error)
- type Accumulator
- func (inst *Accumulator) CoveredBitmap() (covered *roaring.Bitmap)
- func (inst *Accumulator) Fold(snap *covsnap.CounterSnapshot, sampledAtUnixMs int64) (upd *covsnap.Update, err error)
- func (inst *Accumulator) Meta() (meta *covsnap.MetaProfile)
- func (inst *Accumulator) Seq() (seq uint64)
- func (inst *Accumulator) Status() (status covsnap.RunStatus)
- type AccumulatorOptions
- type Collector
- type Sampler
- func (inst *Sampler) Close() (err error)
- func (inst *Sampler) CoveredBitmap() (covered *roaring.Bitmap)
- func (inst *Sampler) Meta() (meta *covsnap.MetaProfile)
- func (inst *Sampler) MetaBlob() (blob []byte)
- func (inst *Sampler) Sample() (upd *covsnap.Update, err error)
- func (inst *Sampler) Seq() (seq uint64)
- func (inst *Sampler) Status() (status covsnap.RunStatus)
- type SamplerOptions
Constants ¶
const DefaultRestateEvery = 60
DefaultRestateEvery is the default full re-statement period in ticks: at the sampler's default cadence this bounds how long a consumer that lost a delta stays stale.
Variables ¶
var CoverageFlags = []cli.Flag{ &cli.StringFlag{ Name: "coverageTrapDir", Category: "coverage", Usage: "Will write cover information to the dir whenever the program receives SIGUSR1. Use -cover -covermode=atomic to compile the program.", Action: func(context *cli.Context, s string) error { if s != "" { err := ProbeRuntimeSupport() if err != nil { return eh.Errorf("program has no runtime coverage snapshot support (build with -cover -covermode=atomic): %w", err) } sig := syscall.SIGUSR1 collector := NewCollector() err = collector.SetupSignalTrap(path.Join(s, "counters"), path.Join(s, "meta"), sig) if err != nil { return eh.Errorf("unable to setup signal trap: %w", err) } log.Info().Str("directory", s).Stringer("signal", sig).Msg("successfully setup signal trap for writing cover information") } return nil }, }, }
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMBlocked, WASMJS: packageprops.WASMBlocked, WASMFreestanding: packageprops.WASMBlocked, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
func DecodeCounters ¶ added in v0.0.20
func DecodeCounters(data []byte) (snap *covsnap.CounterSnapshot, err error)
DecodeCounters decodes the blob written by runtime/coverage.WriteCounters (equally a GOCOVERDIR covcounters.* file) into the periodic snapshot model. The blob carries entries only for functions that executed; Counters[i] pairs with the function's Units[i] from the MetaProfile whose Hash equals MetaHash.
func DecodeMeta ¶ added in v0.0.20
func DecodeMeta(data []byte) (prof *covsnap.MetaProfile, err error)
DecodeMeta decodes the blob written by runtime/coverage.WriteMeta (equally a GOCOVERDIR covmeta.* file) into the once-per-build lookup model, assigning the profile-wide global unit index along the way.
func ProbeRuntimeSupport ¶ added in v0.0.20
func ProbeRuntimeSupport() (err error)
ProbeRuntimeSupport reports whether the running binary can snapshot coverage counters at runtime. WriteCounters — the capability the signal trap and the ADR-0169 sampler rely on — requires a binary built with -cover -covermode=atomic (set and count modes refuse runtime snapshots). Probing with WriteCounters itself is side-effect-free; ClearCounters, the obvious alternative, resets the counters accumulated so far.
In test binaries the probe always errors: meta-data finalization is deferred to an exit hook there, so the success path is reachable only in a real binary.
Types ¶
type Accumulator ¶ added in v0.0.20
type Accumulator struct {
// contains filtered or unexported fields
}
Accumulator folds successive counter snapshots of one build into the cumulative covered set and pre-aggregated updates (ADR-0169 §SD3). It is pure state — no runtime/coverage, no clock — so it is fully testable with synthetic snapshots; Sampler wires it to the live runtime.
Coverage is treated as monotone: units only ever enter the covered set. A snapshot with fewer or zeroed counters (only possible after ClearCounters, which nothing in this design calls) folds as "no change".
Fold has a single-writer contract (one sampler goroutine); the read accessors are safe to call concurrently from provider goroutines.
func NewAccumulator ¶ added in v0.0.20
func NewAccumulator(meta *covsnap.MetaProfile, opts AccumulatorOptions) (inst *Accumulator)
func (*Accumulator) CoveredBitmap ¶ added in v0.0.20
func (inst *Accumulator) CoveredBitmap() (covered *roaring.Bitmap)
CoveredBitmap returns a clone of the cumulative covered set.
func (*Accumulator) Fold ¶ added in v0.0.20
func (inst *Accumulator) Fold(snap *covsnap.CounterSnapshot, sampledAtUnixMs int64) (upd *covsnap.Update, err error)
Fold absorbs one counter snapshot and returns the tick's update. The sampledAtUnixMs stamp is the caller's so the engine stays clock-free.
func (*Accumulator) Meta ¶ added in v0.0.20
func (inst *Accumulator) Meta() (meta *covsnap.MetaProfile)
Meta returns the build's lookup profile. The profile is immutable after decode; callers must not mutate it.
func (*Accumulator) Seq ¶ added in v0.0.20
func (inst *Accumulator) Seq() (seq uint64)
Seq returns the number of folds so far.
func (*Accumulator) Status ¶ added in v0.0.20
func (inst *Accumulator) Status() (status covsnap.RunStatus)
Status returns the current absolute cumulative totals.
type AccumulatorOptions ¶ added in v0.0.20
type AccumulatorOptions struct {
// RestateEvery emits a full re-statement every N folds; 0 selects
// DefaultRestateEvery, 1 makes every update full. The first fold is
// always full.
RestateEvery uint64
}
AccumulatorOptions parameterize the fold engine.
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
func NewCollector ¶
func NewCollector() *Collector
type Sampler ¶ added in v0.0.20
type Sampler struct {
// contains filtered or unexported fields
}
Sampler acquires periodic coverage updates from the running process: WriteCounters → decode → Accumulator.Fold (ADR-0169 §SD3/§SD4). It is the BundleSampler analog of the sysmetrics pipeline — the bus producer (M3) owns the ticker and calls Sample; construction fails cleanly on a binary without -cover -covermode=atomic, and the caller idles.
Sample has a single-caller contract (the producer goroutine); Meta, MetaBlob, Status and CoveredBitmap are safe for concurrent readers.
func NewSampler ¶ added in v0.0.20
func NewSampler(opts SamplerOptions) (inst *Sampler, err error)
func (*Sampler) Close ¶ added in v0.0.20
Close exists for producer-side symmetry with other samplers; the coverage sampler holds no resources.
func (*Sampler) CoveredBitmap ¶ added in v0.0.20
CoveredBitmap returns a clone of the cumulative covered set.
func (*Sampler) Meta ¶ added in v0.0.20
func (inst *Sampler) Meta() (meta *covsnap.MetaProfile)
Meta returns the build's decoded lookup profile.
func (*Sampler) MetaBlob ¶ added in v0.0.20
MetaBlob returns the raw meta-data blob of this build — the once-per-hash payload the persistence tee ingests (ADR-0169 §SD6). Callers must not mutate it.
func (*Sampler) Sample ¶ added in v0.0.20
Sample snapshots the live counters and folds them into one update.
type SamplerOptions ¶ added in v0.0.20
type SamplerOptions struct {
// RestateEvery is forwarded to the fold engine; see AccumulatorOptions.
RestateEvery uint64
}
SamplerOptions parameterize the live sampler.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package covsnap holds the pure-data model of Go coverage (ADR-0169 §SD2/§SD3): the decoded meta-data and counter snapshots, and the sampler's pre-aggregated emission model.
|
Package covsnap holds the pure-data model of Go coverage (ADR-0169 §SD2/§SD3): the decoded meta-data and counter snapshots, and the sampler's pre-aggregated emission model. |