dashbored

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package dashbored is the generated Dashbored widget.

Edit the widget document and regenerate; edits here are overwritten.

Index

Constants

View Source 
const (
	DashboredName    = "Dashbored"
	DashboredRegion  = "widget.candaws.dashbored"
	DashboredPalette = "fieldStation"
	DashboredTitleID = "widget.candaws.dashbored-title"
)

This widget's identity. The region is the only one that crosses the wire: a patch names it, so changing it is a client-visible change. The palette is a name a host resolves to values; this widget carries no colour of its own. The title id is what the widget's landmark is labelled by.

View Source 
const (
	DashboredEventToggleSilence = "widget.candaws.dashbored.silence"
	DashboredEventScrapeReport  = "widget.candaws.dashbored.report"
)

The wire names this widget accepts. The set is exhaustive and default-deny: a name absent from the registration is refused before any reducer runs.

View Source 
const (
	DashboredEventScrapeReportFieldScrapeSequence   = "scrape_sequence"
	DashboredEventScrapeReportFieldFiringAlert      = "firing_alert"
	DashboredEventScrapeReportFieldCollectorsUp     = "collectors_up"
	DashboredEventScrapeReportFieldSamplesPerSecond = "samples_per_second"
	DashboredEventScrapeReportFieldRetentionDays    = "retention_days"
	DashboredEventScrapeReportFieldQueryWindowHours = "query_window_hours"
	DashboredEventScrapeReportFieldAggregatorUp     = "aggregator_up"
	DashboredEventScrapeReportFieldBreaching        = "breaching"
)

The wire field names each event carries. They are the other half of an event's contract: the widget reads these out of a delivery, and whatever produced the delivery wrote them in. Registration.Payloads carries the same names as data, for a host that fills an event it cannot name at compile time.

Variables

View Source 
var (
	// ErrCollectorCount is a collector count outside [1, maxCollectors].
	ErrCollectorCount = errors.New("dashbored: the collector count is out of range")

	// ErrScrapeInterval is a scrape interval that is not positive.
	ErrScrapeInterval = errors.New("dashbored: the scrape interval is not positive")

	// ErrFlushInterval is a flush interval that is not positive, or one shorter
	// than a scrape — which reports a rate over a window nothing arrived in.
	ErrFlushInterval = errors.New("dashbored: the flush interval does not clear the scrape interval")

	// ErrReservoir is a reservoir size below one: a collector that samples
	// nothing is a collector that observes nothing.
	ErrReservoir = errors.New("dashbored: the reservoir size is below one")

	// ErrThreshold is a breach threshold outside (0, 1], the range an
	// observation can be in.
	ErrThreshold = errors.New("dashbored: the breach threshold is not an observable value")

	// ErrDebounce is a debounce below one, which fires an alert on a single
	// observation and resolves it on the next.
	ErrDebounce = errors.New("dashbored: the debounce is below one")

	// ErrAlertName is an empty alert name. The card interpolates it, and an
	// empty one renders as a sentence with a hole in it.
	ErrAlertName = errors.New("dashbored: the alert name is empty")

	// ErrRetention is a retention or query window that is not positive.
	ErrRetention = errors.New("dashbored: the retention or query window is not positive")
)

The faults this engine reports, each a sentinel.

Functions

func DashboredView 

func DashboredView(state DashboredState) templ.Component

DashboredView draws the Dashbored widget's default live region.

func DashboredViewAt 

func DashboredViewAt(state DashboredState, region string) templ.Component

DashboredViewAt draws one instance in its host-assigned live region.

Every value in it is a pure read of state and region: equal inputs render byte-identical markup: that comparison is what suppresses a patch nobody needs.

func ReportFields 

func ReportFields(view MetricsView) map[string]string

ReportFields is one metrics view as the scrapeReport event carries it.

Types

type Config 

type Config struct {
	// Collectors is how many probes feed the aggregator.
	Collectors int

	// ScrapeInterval is how often each collector observes.
	ScrapeInterval time.Duration

	// FlushInterval is how often the aggregator rolls up and reports a rate.
	FlushInterval time.Duration

	// ReservoirSize is how many observations a collector's reservoir holds.
	ReservoirSize int

	// BreachThreshold is the observation above which a sample is a breach, in
	// (0, 1].
	BreachThreshold float64

	// DebounceWindows is how many flush windows an alert must keep breaching
	// before it fires, and how many quiet ones before it resolves.
	DebounceWindows int

	// AlertName is what the card renders when something is firing.
	AlertName string

	// RetentionDays is how long the service says it keeps your data, and
	// QueryWindowHours is how much of that you can ask about. The two being
	// different is the product.
	RetentionDays    int
	QueryWindowHours int

	// Seed seeds the per-collector random streams.
	Seed int64
}

Config is one telemetry pipeline's shape and pace. Every field is required.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig is the demo's own pace: three collectors, a scrape a second, a threshold high enough that a breach is news, and the retention numbers from the pricing page.

func (Config) Validate 

func (config Config) Validate() error

Validate reports the first fault in a configuration.

type Dashbored 

type Dashbored[I live.IIdentity] struct {
	// contains filtered or unexported fields
}

Dashbored is the generated Dashbored widget.

I is the HOST's identity type, threaded through and never read: a widget document names no host, no address and no credential, so nothing here can look at an identity. It is a type parameter because the SDK's contract carries one — live.Session stopped erasing the application's identity type on 2026-09-03 — and a generated widget must fit whatever host registers it.

func NewDashbored 

func NewDashbored[I live.IIdentity]() *Dashbored[I]

NewDashbored returns the widget a host registers, instantiated on that host's own identity type.

func NewDashboredAt 

func NewDashboredAt[I live.IIdentity](region string) *Dashbored[I]

NewDashboredAt gives one instance its host-assigned region. The host validates region syntax and uniqueness when assembling its live configuration.

func (*Dashbored[I]) Dirty 

func (instance *Dashbored[I]) Dirty(previous DashboredState, next DashboredState) bool

Dirty reports whether a transition may have changed this widget's markup: the state fields its bindings, its predicates and its tick read, and no others.

func (*Dashbored[I]) Mount 

func (instance *Dashbored[I]) Mount(
	ctx context.Context, session live.Session[I],
) (DashboredState, []live.Effect[I], error)

Mount opens one session's copy of the widget. It schedules no effect: the streams this widget declared are the host's to open, because a widget document names no host, no address and no credential.

func (*Dashbored[I]) Reduce 

func (instance *Dashbored[I]) Reduce(
	state DashboredState, event live.Event,
) (DashboredState, []live.Effect[I])

Reduce is the pure transition from one state to the next. It performs no I/O, reads no clock and mutates nothing it was given.

func (*Dashbored[I]) Register 

func (instance *Dashbored[I]) Register() widget.Registration

Register declares this instance's definition and assigned region.

Events are the names a browser may send; Internal are the names only a declared stream delivers, which the host routes without registering.

func (*Dashbored[I]) Render 

func (instance *Dashbored[I]) Render(state DashboredState) templ.Component

Render draws the widget's live region. It is a pure function of state: equal state renders byte-identical markup.

func (*Dashbored[I]) Snapshot 

func (instance *Dashbored[I]) Snapshot(state DashboredState) widget.Snapshot

Snapshot projects state into ordered name/value pairs, in state-field declaration order.

func (*Dashbored[I]) Unmount 

func (instance *Dashbored[I]) Unmount(ctx context.Context, session live.Session[I], state DashboredState)

Unmount releases what the session held. This widget holds nothing.

type DashboredState 

type DashboredState struct {
	// ScrapeSequence is the "scrapeSequence" state field, declared type counter.
	ScrapeSequence uint64

	// FiringAlert is the "firingAlert" state field, declared type text.
	FiringAlert string

	// CollectorsUp is the "collectorsUp" state field, declared type count.
	CollectorsUp int64

	// SamplesPerSecond is the "samplesPerSecond" state field, declared type count.
	SamplesPerSecond int64

	// RetentionDays is the "retentionDays" state field, declared type count.
	RetentionDays int64

	// QueryWindowHours is the "queryWindowHours" state field, declared type count.
	QueryWindowHours int64

	// AggregatorUp is the "aggregatorUp" state field, declared type flag.
	AggregatorUp bool

	// Breaching is the "breaching" state field, declared type flag.
	Breaching bool

	// Silenced is the "silenced" state field, declared type flag.
	Silenced bool

	// QueryLag is the "queryLag" state field, declared type flag.
	QueryLag bool
}

DashboredState is this widget's own state, and the type argument every method below is written in. The host holds it without knowing it; nothing in this file asserts it back, because nothing in this file ever loses it.

func (DashboredState) AggregatorCaptionLabel 

func (state DashboredState) AggregatorCaptionLabel() string

AggregatorCaptionLabel is the "aggregatorCaptionLabel" label.

func (DashboredState) AggregatorCaptionText 

func (state DashboredState) AggregatorCaptionText() string

AggregatorCaptionText is the "aggregatorCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) AggregatorLabel 

func (state DashboredState) AggregatorLabel() string

AggregatorLabel is the "aggregatorLabel" label.

func (DashboredState) AlertIndicatorTone 

func (state DashboredState) AlertIndicatorTone() string

AlertIndicatorTone is the "alertIndicator" indicator's tone: positive while its predicate holds, warning otherwise.

func (DashboredState) AlertStatLabel 

func (state DashboredState) AlertStatLabel() string

AlertStatLabel is the "alertStatLabel" label.

func (DashboredState) AlertStatusLabel 

func (state DashboredState) AlertStatusLabel() string

AlertStatusLabel is the "alertStatusLabel" label.

func (DashboredState) AlertStatusText 

func (state DashboredState) AlertStatusText() string

AlertStatusText is the "alertStatusText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) AlerterCaptionLabel 

func (state DashboredState) AlerterCaptionLabel() string

AlerterCaptionLabel is the "alerterCaptionLabel" label.

func (DashboredState) AlerterCaptionText 

func (state DashboredState) AlerterCaptionText() string

AlerterCaptionText is the "alerterCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) AlerterLabel 

func (state DashboredState) AlerterLabel() string

AlerterLabel is the "alerterLabel" label.

func (DashboredState) BreachLegendLabel 

func (state DashboredState) BreachLegendLabel() string

BreachLegendLabel is the "breachLegendLabel" label.

func (DashboredState) Collecting 

func (state DashboredState) Collecting() bool

Collecting is the "collecting" predicate.

func (DashboredState) CollectorCaptionLabel 

func (state DashboredState) CollectorCaptionLabel() string

CollectorCaptionLabel is the "collectorCaptionLabel" label.

func (DashboredState) CollectorCaptionText 

func (state DashboredState) CollectorCaptionText() string

CollectorCaptionText is the "collectorCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) CollectorOneLabel 

func (state DashboredState) CollectorOneLabel() string

CollectorOneLabel is the "collectorOneLabel" label.

func (DashboredState) CollectorStatLabel 

func (state DashboredState) CollectorStatLabel() string

CollectorStatLabel is the "collectorStatLabel" label.

func (DashboredState) CollectorStatText 

func (state DashboredState) CollectorStatText() string

CollectorStatText is the "collectorStatText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) CollectorThreeLabel 

func (state DashboredState) CollectorThreeLabel() string

CollectorThreeLabel is the "collectorThreeLabel" label.

func (DashboredState) CollectorTwoLabel 

func (state DashboredState) CollectorTwoLabel() string

CollectorTwoLabel is the "collectorTwoLabel" label.

func (DashboredState) MetricsDescriptionText 

func (state DashboredState) MetricsDescriptionText() string

MetricsDescriptionText is the "metricsDescriptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) MotionActive 

func (state DashboredState) MotionActive() bool

MotionActive is this widget's compiled motion gate: everything its motion block requires, and none of what it forbids. The host's own connection status is the gate's other half and is applied by the stylesheet, so an animation cannot run against a dead connection whatever this returns.

func (DashboredState) MotionActiveText 

func (state DashboredState) MotionActiveText() string

MotionActiveText renders the gate into the attribute the stylesheet selects on.

func (DashboredState) MotionTickID 

func (state DashboredState) MotionTickID() string

MotionTickID is the scene's identity for one tick.

Every animation is finite and none repeats, so what starts one again is a new element: the scene carries this as its id, the tick advances, and the picture moves exactly as often as the data does.

func (DashboredState) MotionTickIDAt 

func (state DashboredState) MotionTickIDAt(region string) string

MotionTickIDAt namespaces the scene's tick identity under its live instance.

func (DashboredState) Observing 

func (state DashboredState) Observing() bool

Observing is the "observing" predicate.

func (DashboredState) Quiet 

func (state DashboredState) Quiet() bool

Quiet is the "quiet" predicate.

func (DashboredState) RetentionStatLabel 

func (state DashboredState) RetentionStatLabel() string

RetentionStatLabel is the "retentionStatLabel" label.

func (DashboredState) SampleLegendLabel 

func (state DashboredState) SampleLegendLabel() string

SampleLegendLabel is the "sampleLegendLabel" label.

func (DashboredState) SceneDescriptionLabel 

func (state DashboredState) SceneDescriptionLabel() string

SceneDescriptionLabel is the "sceneDescriptionLabel" label.

func (DashboredState) SilenceCaptionLabel 

func (state DashboredState) SilenceCaptionLabel() string

SilenceCaptionLabel is the "silenceCaptionLabel" label.

func (DashboredState) SilenceCaptionText 

func (state DashboredState) SilenceCaptionText() string

SilenceCaptionText is the "silenceCaptionText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) SilenceControlPressedText 

func (state DashboredState) SilenceControlPressedText() string

SilenceControlPressedText renders the "silenceControl" control's pressed state.

func (DashboredState) SourceLabel 

func (state DashboredState) SourceLabel() string

SourceLabel is the "sourceLabel" label.

func (DashboredState) ThroughputStatLabel 

func (state DashboredState) ThroughputStatLabel() string

ThroughputStatLabel is the "throughputStatLabel" label.

func (DashboredState) ThroughputStatText 

func (state DashboredState) ThroughputStatText() string

ThroughputStatText is the "throughputStatText" binding. The first matching clause wins and the otherwise arm is always present, so it is total.

func (DashboredState) TitleLabel 

func (state DashboredState) TitleLabel() string

TitleLabel is the "titleLabel" label.

func (DashboredState) WindowStatLabel 

func (state DashboredState) WindowStatLabel() string

WindowStatLabel is the "windowStatLabel" label.

type MetricsView 

type MetricsView struct {
	// Sequence is this view's position in the stream, from 1.
	Sequence uint64

	// FiringAlert is the name of what is firing, or empty when nothing is. It
	// is the fleet's third text field, and it exists because the disjunction
	// behind a breach — p99 or error rate — lives in the engine, so the card
	// cannot say which fired without being told the name.
	FiringAlert string

	// CollectorsUp is how many collectors the aggregator has not had a
	// departure notice from.
	CollectorsUp int

	// SamplesPerSecond is the ingest rate over the last flush window.
	SamplesPerSecond int

	// Observations is how many samples the histogram is made of.
	Observations int

	// RetentionDays is how long the service says it keeps your data, and
	// QueryWindowHours how much of it you may ask about. They never change, and
	// the difference between them is the joke rendered as data.
	RetentionDays    int
	QueryWindowHours int

	// AggregatorUp is whether the aggregator is still ingesting. It goes false
	// exactly once, when the last collector's departure notice arrives.
	AggregatorUp bool

	// Breaching is whether the alerter has anything firing.
	Breaching bool
}

MetricsView is what the pipeline tells anybody, and it is deliberately the shape the Dashbored card's `scrapeReport` event carries.

func (MetricsView) Quiet 

func (view MetricsView) Quiet() bool

Quiet reports whether nothing is wrong, which is the only thing a metrics service ever wants to say. It is the `forbids`-only predicate the card declares, and this is the same statement on the engine's side.

type QueryResult 

type QueryResult struct {
	// Buckets is the histogram, in bound order, as a copy.
	Buckets []int

	// Observations is how many samples the buckets are made of.
	Observations int

	// Median is the p50, which is the one number this service surfaces.
	Median float64
}

QueryResult is one answer to a query.

Buckets is a copy: the aggregator is the only reader and writer of its own, and a caller holding a slice that aliased them would be a second reader of the one thing this engine promises has one.

type Telemetry 

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

Telemetry is one Dashbored pipeline running in one process: the fleet's own console, and a fan-in.

It holds channels and nothing else. Every reservoir, the histogram buckets, the firing set and the published view are locals of goroutines Telemetry.Run starts.

func NewTelemetry 

func NewTelemetry(config Config) (*Telemetry, error)

NewTelemetry builds a pipeline and starts nothing.

func (*Telemetry) Config 

func (telemetry *Telemetry) Config() Config

Config is the configuration this pipeline was built from.

func (*Telemetry) Query 

func (telemetry *Telemetry) Query(ctx context.Context) (QueryResult, error)

Query asks the aggregator for the rolled-up view, and waits for its answer.

The reply channel is made here and travels with the request, so the answer reaches exactly the caller that asked and the histogram never leaves the goroutine that owns it.

func (*Telemetry) Retire 

func (telemetry *Telemetry) Retire()

Retire asks every collector to leave.

What happens next is the demonstration: each collector sends exactly one departure notice, the aggregator counts them down, and when the count reaches zero it reports that ingest has stopped. "Have all the producers finished" is a message rather than a shared integer, so there is nothing to lock and nothing to get wrong about the last one.

A second call is a no-op rather than a panic: the token can be taken once.

func (*Telemetry) Run 

func (telemetry *Telemetry) Run(ctx context.Context) error

Run starts every goroutine and returns when the context ends and all of them have stopped. The only error it has is being called twice.

func (*Telemetry) Watch 

func (telemetry *Telemetry) Watch(ctx context.Context) (<-chan MetricsView, error)

Watch is the aggregator stream the card's declared source resolves to.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.