Documentation
¶
Overview ¶
Package counters is the generic user-defined counter API: one line in application code (isutools.Count("cache_hit")) makes cache hit/miss and similar custom events visible per benchmark generation.
Index ¶
- Constants
- Variables
- type Entry
- type Frozen
- type GenerationCollector
- func (c *GenerationCollector) BeginBoundary(ctx context.Context, runID string, ep runctl.Epoch) (runctl.BoundaryResult, error)
- func (c *GenerationCollector) Collect(h runctl.GenerationHandle) (any, error)
- func (c *GenerationCollector) Drain(ctx context.Context, h runctl.GenerationHandle) error
- func (c *GenerationCollector) Freeze(ctx context.Context, runID string, ep runctl.Epoch) (runctl.BoundaryResult, error)
- func (c *GenerationCollector) Name() string
- func (c *GenerationCollector) Release(h runctl.GenerationHandle)
- type Registry
Constants ¶
const ( // DefaultMaxNames bounds dynamic counter identities per generation. DefaultMaxNames = 1024 // MaxNameBytes bounds the retained memory for each identity. MaxNameBytes = 128 // OverflowName receives observations outside either bound. OverflowName = "(other)" )
const SectionName = "counters"
SectionName is the snapshot section this collector fills. It is the key the existing snapshot and health output already use for counters.
Variables ¶
var ( // ErrForeignHandle rejects a handle minted by another collector or by // another instance of this one. ErrForeignHandle = errors.New("counters: generation handle belongs to another collector") // ErrHandleReleased reports a handle whose data was already freed. ErrHandleReleased = errors.New("counters: generation handle was released") // ErrNotDrained reports a generation that has not been materialised yet, // so no fixed value exists to collect. ErrNotDrained = errors.New("counters: generation was not drained") )
Handle errors. They are sentinels because the run controller maps a Collect failure onto a stable machine-readable code and must be able to tell "this handle is not mine" from "this generation has no data yet".
var Default = NewRegistry()
Default is the registry the facade helpers write into.
Functions ¶
This section is empty.
Types ¶
type Frozen ¶ added in v1.2.0
type Frozen struct {
// Entries are sorted by count descending, ties by name.
Entries []Entry `json:"entries"`
// Dropped counts observations merged into OverflowName.
Dropped uint64 `json:"dropped"`
}
Frozen is one closed counter generation.
type GenerationCollector ¶ added in v1.2.0
type GenerationCollector struct {
// contains filtered or unexported fields
}
GenerationCollector adapts a counter registry to runctl.GenerationCollector.
A boundary swaps the counter table out and nothing more, so it cannot block: counters have no in-flight work to settle, only a map to hand over. Materialising and sorting that map is deferred to Drain, which keeps the boundary itself a pointer swap and gives the context somewhere to apply.
func NewGenerationCollector ¶ added in v1.2.0
func NewGenerationCollector(registry *Registry) *GenerationCollector
NewGenerationCollector wraps a registry. A nil registry means the package default, which is where the facade helpers count.
func (*GenerationCollector) BeginBoundary ¶ added in v1.2.0
func (c *GenerationCollector) BeginBoundary(ctx context.Context, runID string, ep runctl.Epoch) (runctl.BoundaryResult, error)
BeginBoundary swaps in an empty counter table and returns a handle to the table it just replaced.
func (*GenerationCollector) Collect ¶ added in v1.2.0
func (c *GenerationCollector) Collect(h runctl.GenerationHandle) (any, error)
Collect returns the frozen counter table. It reads only what Drain fixed and never touches the registry's current table.
func (*GenerationCollector) Drain ¶ added in v1.2.0
func (c *GenerationCollector) Drain(ctx context.Context, h runctl.GenerationHandle) error
Drain materialises the swapped-out table.
The boundary already detached it, so there is no in-flight work to wait for and a settled generation is reported as complete even when ctx is already done: failing it would drop a section that is not actually missing anything.
func (*GenerationCollector) Freeze ¶ added in v1.2.0
func (c *GenerationCollector) Freeze(ctx context.Context, runID string, ep runctl.Epoch) (runctl.BoundaryResult, error)
Freeze seals the running counter table. Counts recorded after it belong to the next generation, outside the run.
func (*GenerationCollector) Name ¶ added in v1.2.0
func (c *GenerationCollector) Name() string
Name identifies the snapshot section this collector fills.
func (*GenerationCollector) Release ¶ added in v1.2.0
func (c *GenerationCollector) Release(h runctl.GenerationHandle)
Release drops the frozen table. It is idempotent, and a handle this collector never minted is ignored rather than reported: Release has no error channel and must not panic into the caller.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is a concurrency-safe named counter set.
func (*Registry) Dropped ¶ added in v1.1.0
Dropped returns how many observations were merged into OverflowName.
Source Files