Help us shape the future of Go! Take the 2026 Go Developer Survey

benchworkload

package
v0.1.0-rc.41 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2026 License: BSD-3-Clause Imports: 37 Imported by: 0

Documentation

Overview

Package benchworkload contains the publisher and visitor workloads shared by local runtime tests and deployed benchmarks. runners own setup and cleanup.

Index

Constants

View Source 
const (
	BandwidthDownstream    = "downstream"
	BandwidthUpstream      = "upstream"
	BandwidthBidirectional = "bidirectional"
)
View Source 
const RequestTimeout = 5 * time.Second

Variables

View Source 
var ErrBandwidthLate = errors.New("bandwidth completed after its deadline")

ErrBandwidthLate identifies a complete transfer that missed its deadline.

Functions

func Assignment 

func Assignment(total, count, index int) int

func CancellationOnly 

func CancellationOnly(err error) bool

errors.Is alone would hide a close failure joined with cancellation.

func Origin 

func Origin(size int) http.Handler

func Payload 

func Payload(size int) []byte

func PublicURLIndexes 

func PublicURLIndexes(total, count, index int) []int

func ServeTCPEcho 

func ServeTCPEcho(ctx context.Context, listener net.Listener) error

ServeTCPEcho preserves request boundaries and echoes a bounded frame unchanged. it joins accepted sockets on cancellation, including incomplete client writes.

func WaitUntil 

func WaitUntil(ctx context.Context, at time.Time) error

Types

type BandwidthConfig 

type BandwidthConfig struct {
	Direction      string        `json:"direction"`
	Streams        int           `json:"streams_per_direction"`
	BytesPerSecond int64         `json:"bytes_per_second_per_direction"`
	Start          time.Time     `json:"start"`
	Duration       time.Duration `json:"duration"`
}

BandwidthConfig describes a fixed-rate transfer phase. Streams is the number of streams per active direction.

type BandwidthResult 

type BandwidthResult struct {
	Direction              string                  `json:"direction"`
	StreamsPerDirection    int                     `json:"streams_per_direction"`
	TargetBytesPerSecond   int64                   `json:"target_bytes_per_second_per_direction"`
	SetupDuration          time.Duration           `json:"setup_duration,omitempty"`
	TargetDuration         time.Duration           `json:"target_duration"`
	StartedAt              time.Time               `json:"started_at"`
	Elapsed                time.Duration           `json:"elapsed"`
	ExpectedUploadBytes    int64                   `json:"expected_upload_bytes"`
	UploadBytes            int64                   `json:"upload_bytes"`
	ExpectedDownloadBytes  int64                   `json:"expected_download_bytes"`
	DownloadBytes          int64                   `json:"download_bytes"`
	UploadBytesPerSecond   float64                 `json:"upload_bytes_per_second"`
	DownloadBytesPerSecond float64                 `json:"download_bytes_per_second"`
	Failures               int                     `json:"failures"`
	FailureSamples         []string                `json:"failure_samples,omitempty"`
	Streams                []BandwidthStreamResult `json:"streams,omitempty"`
	PerSecond              []BandwidthSecond       `json:"per_second,omitempty"`
}

BandwidthResult records exact application bytes transferred by a phase.

func (BandwidthResult) CorrectnessErr 

func (r BandwidthResult) CorrectnessErr() error

CorrectnessErr reports missing, corrupted, or failed transfers without classifying a complete but late transfer as lost data.

func (BandwidthResult) Err 

func (r BandwidthResult) Err() error

Err reports incomplete or late transfers.

type BandwidthSecond 

type BandwidthSecond struct {
	Second        int   `json:"second"`
	UploadBytes   int64 `json:"upload_bytes"`
	DownloadBytes int64 `json:"download_bytes"`
}

type BandwidthSession 

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

BandwidthSession owns one verified, reusable visitor connection per stream. prepare it before setting the measurement start time.

func (*BandwidthSession) Close 

func (s *BandwidthSession) Close()

func (*BandwidthSession) Run 

func (s *BandwidthSession) Run(ctx context.Context, start time.Time, duration time.Duration) (BandwidthResult, error)

Run measures prepared streams against one common start time.

type BandwidthStreamResult 

type BandwidthStreamResult struct {
	Index          int           `json:"index"`
	URL            string        `json:"url"`
	Direction      string        `json:"direction"`
	ExpectedBytes  int64         `json:"expected_bytes"`
	Bytes          int64         `json:"bytes"`
	FirstByteDelay time.Duration `json:"first_byte_delay,omitempty"`
	LastByteDelay  time.Duration `json:"last_byte_delay,omitempty"`
	Error          string        `json:"error,omitempty"`
}

type Coordination 

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

func NewCoordination 

func NewCoordination(endpoint, token string) (*Coordination, error)

func (*Coordination) Get 

func (c *Coordination) Get(ctx context.Context, name string, value any) (bool, error)

func (*Coordination) Put 

func (c *Coordination) Put(ctx context.Context, name string, value any) error

func (*Coordination) Wait 

func (c *Coordination) Wait(ctx context.Context, name string, value any) error

func (*Coordination) WorkloadContext 

func (c *Coordination) WorkloadContext(parent context.Context) (context.Context, func())

WorkloadContext also stops participants measuring when a failure occurs. Stop joins its watcher; cleanup reports its outcome with a separate context.

type Coordinator 

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

Coordinator stores immutable run events. the runner owns the phase sequence; participants acknowledge readiness/results under their own event names.

func NewCoordinator 

func NewCoordinator() *Coordinator

func (*Coordinator) Handler 

func (s *Coordinator) Handler(token string) http.Handler

type HeldStream 

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

func (*HeldStream) Alive 

func (s *HeldStream) Alive() bool

func (*HeldStream) BytesReceived 

func (s *HeldStream) BytesReceived() int64

BytesReceived distinguishes ongoing delivery from a stalled, still-open socket.

func (*HeldStream) Close 

func (s *HeldStream) Close() error

type Histogram 

type Histogram struct {
	BoundsMilliseconds  []float64 `json:"bounds_milliseconds"`
	Counts              []uint64  `json:"counts"`
	Count               uint64    `json:"count"`
	SumMilliseconds     float64   `json:"sum_milliseconds"`
	MinimumMilliseconds float64   `json:"minimum_milliseconds"`
	MaximumMilliseconds float64   `json:"maximum_milliseconds"`
}

histogram counts are cumulative and use the production duration buckets.

func NewHistogram 

func NewHistogram(samples []time.Duration) *Histogram

func (*Histogram) Merge 

func (h *Histogram) Merge(other Histogram) error

func (*Histogram) Observe 

func (h *Histogram) Observe(duration time.Duration)

func (*Histogram) Percentile 

func (h *Histogram) Percentile(percentile int) *float64

type Phase 

type Phase struct {
	Name        string           `json:"name"`
	Start       time.Time        `json:"start"`
	Duration    time.Duration    `json:"duration"`
	URLs        []string         `json:"urls"`
	Bandwidth   *BandwidthConfig `json:"bandwidth,omitempty"`
	Combined    bool             `json:"combined,omitempty"`
	Direct      bool             `json:"direct,omitempty"`
	HeldStreams int              `json:"held_streams,omitempty"`
	CloseHeld   bool             `json:"close_held,omitempty"`
	OpenHeld    bool             `json:"open_held,omitempty"`
	Done        bool             `json:"done,omitempty"`
}

Phase is sent by the coordinator; participants do not copy the scenario sequence. a zero duration requests correctness probes only.

type PublishedPublicURL 

type PublishedPublicURL struct {
	Index      int             `json:"index"`
	Ready      publisher.Event `json:"ready"`
	Activation time.Duration   `json:"activation"`
}

type PublisherConfig 

type PublisherConfig struct {
	Server, Domain, StateRoot, Target string
	HostnamePrefix                    string
	Ephemeral                         bool
	HTTPClient                        *http.Client
	RelayTLS                          *tls.Config
	AllowedIPPrefixes                 []string
	// mixed forces alternating QUIC/TLS-TCP cohorts; auto uses production fallback.
	Transport                   TransportChoice
	QUICDisablePathMTUDiscovery bool
	QUICQlog                    bool
	QUICKeepAlive               time.Duration
	Parallel                    int
	Concurrency                 int
	RateRequests                int
	// StartParallel overrides Parallel only during activation; shutdown has its own bound.
	StartParallel             int
	ReadyTimeout, StopTimeout time.Duration
	DrainTime                 time.Duration
	OnFailure                 func()
	OnActivationFailure       func(index int)
	Observe                   func(int, publisher.Event) error
	Report                    func(index int, err error)
}

type Publishers 

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

func OpenPublishers 

func OpenPublishers(ctx context.Context, config PublisherConfig) (_ *Publishers, retErr error)

func (*Publishers) Close 

func (g *Publishers) Close(ctx context.Context) (ShutdownResult, error)

func (*Publishers) Failures 

func (g *Publishers) Failures() <-chan error

func (*Publishers) Start 

func (g *Publishers) Start(ctx context.Context, indexes []int) ([]PublishedPublicURL, error)

Start returns any ready results collected before failure, then cancels the group. the coordinator must call Close even after partial activation and call lifecycle methods serially.

func (*Publishers) Started 

func (g *Publishers) Started() int

func (*Publishers) Stop 

func (g *Publishers) Stop(ctx context.Context, indexes []int) (ShutdownResult, error)

Stop leaves public URLs running until their bounded shutdown slot is available.

type RequestResult 

type RequestResult struct {
	URL          string        `json:"url,omitempty"`
	Scheduled    time.Time     `json:"scheduled"`
	Started      time.Time     `json:"started"`
	FirstByte    time.Time     `json:"first_body_byte,omitzero"`
	QueueDelay   time.Duration `json:"queue_delay"`
	DNS          time.Duration `json:"dns"`
	Connect      time.Duration `json:"connect"`
	TLS          time.Duration `json:"tls"`
	Duration     time.Duration `json:"duration"`
	Bytes        int64         `json:"bytes"`
	Error        string        `json:"error,omitempty"`
	Timeout      bool          `json:"timeout,omitempty"`
	QueueExpired bool          `json:"queue_expired,omitempty"`
}

type ShutdownResult 

type ShutdownResult struct {
	StartedAt                     time.Time     `json:"started_at"`
	Duration                      time.Duration `json:"duration"`
	Attempts, Successes, Failures int
	Timings                       []time.Duration `json:"timings"`
}

type TCPVisitor 

type TCPVisitor struct {
	PayloadBytes int
	// contains filtered or unexported fields
}

TCPVisitor measures verified request/response bytes through an opaque connector. fresh requests include remote admission/TLS; Connect measures only the local dial.

func (*TCPVisitor) Close 

func (v *TCPVisitor) Close() error

Close is called after Run joins all workers. failed reused sockets are never replaced: silently redialing would turn the reused phase into a fresh phase.

func (*TCPVisitor) Prepare 

func (v *TCPVisitor) Prepare(ctx context.Context, addresses []string, workers int) (Histogram, error)

Prepare opens and verifies reusable sockets before the paced measurement window. each address owns workers sockets so scheduling never hides a pool wait in setup.

func (*TCPVisitor) Run 

func (v *TCPVisitor) Run(ctx context.Context, config VisitorConfig, addresses []string) (VisitorResult, error)

type TransportChoice 

type TransportChoice string

TransportChoice selects a benchmark publisher cohort or production fallback. 

const (
	TransportAuto  TransportChoice = "auto"
	TransportMixed TransportChoice = "mixed"
	TransportQUIC  TransportChoice = "quic"
	TransportTCP   TransportChoice = "tcp"
)

func (TransportChoice) Valid 

func (transport TransportChoice) Valid() bool

type Visitor 

type Visitor struct {
	Roots         *x509.CertPool
	Address       string
	Resolver      *net.Resolver
	Network       string
	SourceAddress *net.TCPAddr
	PayloadBytes  int
}

func (Visitor) Bandwidth 

func (v Visitor) Bandwidth(ctx context.Context, config BandwidthConfig, urls []string) (BandwidthResult, error)

Bandwidth runs paced, byte-verified transfers against the supplied URLs.

func (Visitor) Hold 

func (v Visitor) Hold(parent context.Context, url string) (*HeldStream, error)

func (Visitor) PrepareBandwidth 

func (v Visitor) PrepareBandwidth(ctx context.Context, direction string, streams int, bytesPerSecond int64, urls []string) (*BandwidthSession, error)

PrepareBandwidth establishes and verifies visitor TLS before measurement.

func (Visitor) Request 

func (v Visitor) Request(parent context.Context, url string, scheduled time.Time) (result RequestResult)

func (Visitor) Run 

func (v Visitor) Run(ctx context.Context, config VisitorConfig, urls []string) (VisitorResult, error)

type VisitorConfig 

type VisitorConfig struct {
	Rate, Workers, QueueSlots int
	Start                     time.Time
	Duration                  time.Duration
	// OnResult is serialized and is intended for scenario-specific observations.
	OnResult func(RequestResult)
}

type VisitorResult 

type VisitorResult struct {
	StartedAt      time.Time       `json:"started_at"`
	OfferDuration  time.Duration   `json:"offer_duration"`
	DrainDuration  time.Duration   `json:"drain_duration"`
	Workers        int             `json:"workers"`
	QueueSlots     int             `json:"queue_slots"`
	Rate           int             `json:"rate"`
	Scheduled      int             `json:"scheduled"`
	Started        int             `json:"started"`
	Completed      int             `json:"completed"`
	Successes      int             `json:"successes"`
	Failures       int             `json:"failures"`
	Timeouts       int             `json:"timeouts"`
	Missed         int             `json:"missed"`
	QueueExpired   int             `json:"queue_expired"`
	Bytes          int64           `json:"bytes"`
	QueueDelay     Histogram       `json:"queue_delay"`
	DNS            Histogram       `json:"dns"`
	Connect        Histogram       `json:"connect"`
	TLS            Histogram       `json:"tls"`
	FirstByte      Histogram       `json:"first_body_byte"`
	Total          Histogram       `json:"total"`
	FailuresSample []RequestResult `json:"failure_samples,omitempty"`
}

func (VisitorResult) Err 

func (r VisitorResult) Err() error

func (*VisitorResult) Merge 

func (r *VisitorResult) Merge(other VisitorResult) error

func (*VisitorResult) Observe 

func (r *VisitorResult) Observe(request RequestResult)

Observe adds one completed or queue-expired request to a local summary.

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.