bench

package
v0.0.0-...-43172cb Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Run 

func Run(
	ctx context.Context,
	client *turbopuffer.Client,
	def *Definition,
	cfg RuntimeConfig,
	logger *output.Logger,
) error

Types

type CacheTemperature 

type CacheTemperature string

CacheTemperature is an enum over the possible cache temperatures reported by the turbopuffer API for a given query. 

const (
	CacheTemperatureHot  CacheTemperature = "hot"
	CacheTemperatureWarm CacheTemperature = "warm"
	CacheTemperatureCold CacheTemperature = "cold"
)

Possible cache temperatures reported by the turbopuffer API.

func AllCacheTemperatures 

func AllCacheTemperatures() []CacheTemperature

All returns a slice of all possible CacheTemperature values.

func (CacheTemperature) Valid 

func (ct CacheTemperature) Valid() bool

Valid returns true if the provided CacheTemperature is valid

type Definition 

type Definition struct {
	Name        string          `toml:"name"`
	Duration    time.Duration   `toml:"duration,omitempty"`
	Namespaces  int             `toml:"namespaces"`
	Description string          `toml:"description,omitempty"`
	Setup       SetupDefinition `toml:"setup"`
	Workloads   Workloads       `toml:"workload"`

	// RawTOML is the original TOML source text of the definition file.
	RawTOML string `toml:"-"`
}

Definition defines a benchmark, including the workload and configuration.

func ParseDefinition 

func ParseDefinition(path string) (*Definition, error)

ParseDefinition parses a benchmark definition from a TOML file.

func (*Definition) Init 

func (d *Definition) Init(ctx context.Context, cfg datasource.Config) error

Init initializes the benchmark definition's templates and datasources, so that the templates are ready to be rendered.

type Namespace 

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

Namespace is a handle to a turbopuffer namespace, and is used to perform requests against the namespace.

func NewNamespace 

func NewNamespace(
	ctx context.Context,
	client *turbopuffer.Client,
	name string,
) *Namespace

NewNamespace creates a new namespace handle with a given name. The namespace will use the provided HTTP client to make requests.

func (*Namespace) Clear 

func (n *Namespace) Clear(ctx context.Context) error

Clear deletes all documents from the namespace, effectively resetting it to an empty state. This will delete all documents in the namespace.

func (*Namespace) CurrentSize 

func (n *Namespace) CurrentSize(ctx context.Context) (int64, error)

CurrentSize queries the namespace for its current size, i.e. the number of documents it contains.

func (*Namespace) ID 

func (n *Namespace) ID() string

ID reports the ID of the namespace.

func (*Namespace) Metadata 

func (n *Namespace) Metadata(ctx context.Context) (*turbopuffer.NamespaceMetadata, error)

Metadata queries for namespace metadata.

func (*Namespace) PurgeCache 

func (n *Namespace) PurgeCache(ctx context.Context) error

PurgeCache purges the cache for the namespace, i.e. it ensures that the namespace is in a cold state when the benchmark begins.

func (*Namespace) Query 

func (n *Namespace) Query(ctx context.Context, maxRetries int, queryTmpl Template) (*turbopuffer.QueryPerformance, time.Duration, error)

Query queries the namespace for a given query, generating the query using its query template. Returns server timing information as well as client time duration if successful, i.e. we don't care about the actual query result.

func (*Namespace) Upsert 

func (n *Namespace) Upsert(ctx context.Context, numDocs int, docTmpl, upsertTmpl Template) (time.Duration, int, error)

Upsert upserts a number of documents into the namespace, generating the documents using its upsert template. The caller must be aware of batch sizes, and tune accordingly (i.e. the API may not accept more than a certain number of documents in a single request).

func (*Namespace) UpsertPrerendered 

func (n *Namespace) UpsertPrerendered(
	ctx context.Context,
	upsertChunks [][]byte,
	opts ...option.RequestOption,
) (time.Duration, int, error)

UpsertPrerendered is the same as `Upsert()`, but instead of generating the documents using the upsert template, it takes the upsert request body as a parameter. This is used for pre-rendered documents, i.e. when we are upserting a ton of documents and want to avoid burning excessive CPU.

func (*Namespace) WarmCache 

func (n *Namespace) WarmCache(ctx context.Context) error

WarmCache warms the cache for the namespace, i.e. it ensures that the namespace is in a warm state when the benchmark begins.

type ParetoQueryDistribution 

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

ParetoQueryDistribution is a QueryDistribution that generates indices according to a Pareto distribution.

Internally, maintains an Alias Table for sampling.

func NewParetoQueryDistribution 

func NewParetoQueryDistribution(n int, alpha float64) *ParetoQueryDistribution

NewParetoQueryDistribution creates a new ParetoQueryDistribution.

func (*ParetoQueryDistribution) NextIndex 

func (p *ParetoQueryDistribution) NextIndex() int

type QueryDistribution 

type QueryDistribution interface {
	NextIndex() int
}

QueryDistribution is an interface for types that can generate an index into an array of namespaces according to some distribution.

Has a single method `NextIndex` that returns a value in the range [0, n). To make implementations easier, `n` is internal to the implementation.

type QueryWorkload 

type QueryWorkload struct {
	Datasource  datasource.Kind `toml:"datasource,omitempty"`
	QPS         float64         `toml:"qps"`
	Concurrency int             `toml:"concurrency,omitempty"`
	MaxRetries  int             `toml:"max_retries,omitempty"`
	// ActiveNamespacePct is the percentage of namespaces that will be queried.
	// Defaults to 1.0 (i.e. all namespaces).
	ActiveNamespacePct float64 `toml:"active_namespace_pct,omitempty"`
	// QueryTemplate is the template to use for querying the namespaces.
	QueryTemplate Template `toml:"template"`
	// QueryDistribution is the distribution of queries across the namespaces.
	// Options: "uniform", "round-robin", "pareto".
	QueryDistribution string `toml:"query_distribution,omitempty"`
	// QueryParetoAlpha is the alpha parameter for the Pareto distribution of
	// queries.
	QueryParetoAlpha float64 `toml:"query_pareto_alpha,omitempty"`
}

QueryWorkload defines a query workload.

type Reporter 

type Reporter struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Reporter is used to report on the outcome of a benchmark run by printing out the results to the console and a set of output files.

func StartReporter 

func StartReporter(def *Definition, outputDir string, logger *output.Logger) (*Reporter, error)

StartReporter starts a new reporter.

func (*Reporter) ReportQuery 

func (r *Reporter) ReportQuery(
	workload string,
	namespace string,
	size int,
	clientDuration time.Duration,
	performance *turbopuffer.QueryPerformance,
) error

ReportQuery reports the results of a single query.

func (*Reporter) ReportUpsert 

func (r *Reporter) ReportUpsert(
	workload string,
	namespace string,
	numDocuments int,
	totalBytes int,
	clientDuration time.Duration,
) error

ReportUpsert reports the results of a single upsert.

func (*Reporter) SetIngestResult 

func (r *Reporter) SetIngestResult(bytes int64, ingestDuration, indexedDuration time.Duration, waitedForIndexing bool)

SetIngestResult records the results of the data ingestion (setup) phase.

func (*Reporter) Stop 

func (r *Reporter) Stop() error

Stop stops the reporter and flushes any remaining data. Should be called at the end of a benchmark run.

type RoundRobinQueryDistribution 

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

RoundRobinQueryDistribution is a QueryDistribution that generates indices in a round-robin fashion.

func NewRoundRobinQueryDistribution 

func NewRoundRobinQueryDistribution(n int) *RoundRobinQueryDistribution

NewRoundRobinQueryDistribution creates a new RoundRobinQueryDistribution.

func (*RoundRobinQueryDistribution) NextIndex 

func (r *RoundRobinQueryDistribution) NextIndex() int

type RuntimeConfig 

type RuntimeConfig struct {
	NamespacePrefix              string
	NamespaceSetupConcurrency    int
	NamespaceSetupConcurrencyMax int
	IfNonempty                   string
	OutputDir                    string
	WarmCache                    bool
	PurgeCache                   bool
	Duration                     time.Duration
}

RuntimeConfig holds all user-provided runtime configuration for running a benchmark.

type ServiceConfig 

type ServiceConfig struct {
	APIKey           string
	Endpoint         string
	HostHeader       string
	AllowTLSInsecure bool
}

ServiceConfig holds the configuration for accessing turbopuffer.

func (*ServiceConfig) NewClient 

func (cfg *ServiceConfig) NewClient() turbopuffer.Client

NewClient creates a new turbopuffer client with the given configuration.

type SetupDefinition 

type SetupDefinition struct {
	// Datasource is the datasource to use for the benchmark. It determines
	// which functions are available to the templates and where the source data
	// is pulled from.
	Datasource       datasource.Kind `toml:"datasource"`
	DocumentCount    int             `toml:"document_count"`
	DocumentTemplate Template        `toml:"document_template"`
	UpsertTemplate   Template        `toml:"upsert_template"`
	WaitForIndexing  bool            `toml:"wait_for_indexing,omitempty"`
	WarmCache        bool            `toml:"warm_cache,omitempty"`
	// WaitForCacheHitRatio, if set to a value > 0, configures the benchmark to
	// poll with workload queries after setup until N consecutive queries from
	// each workload report a cache hit ratio >= this threshold.
	WaitForCacheHitRatio float64 `toml:"wait_for_cache_hit_ratio,omitempty"`
	// NamespaceSizeDistribution is the distribution of document counts across
	// the namespaces. Options: "uniform", "lognormal".
	NamespaceSizeDistribution string `toml:"namespace_size_distribution,omitempty"`
	// NamespaceSizeLogNormalMu is the mu parameter for the lognormal distribution
	// of namespace sizes.
	NamespaceSizeLogNormalMu float64 `toml:"namespace_size_lognormal_mu,omitempty"`
	// NamespaceSizeLogNormalSigma is the sigma parameter for the lognormal
	// distribution of namespace sizes.
	NamespaceSizeLogNormalSigma float64 `toml:"namespace_size_lognormal_sigma,omitempty"`
}

SetupDefinition defines the setup for the benchmark.

type Template 

type Template struct {
	*template.Template
	// contains filtered or unexported fields
}

Template holds a text/template.Template so it can be unmarshaled from TOML string values (e.g. inline document_template, query template). The raw text is stored during TOML decoding; actual parsing is deferred to Init() when the full FuncMap is available.

func NewTemplate 

func NewTemplate(src string, funcs template.FuncMap) (Template, error)

NewTemplate creates a Template by parsing the given source with the provided FuncMap. This is useful for constructing templates outside of the TOML definition flow (e.g. the sanity check).

func (*Template) UnmarshalText 

func (t *Template) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler so TOML can decode a string into a Template. Parsing is deferred to Init() so that the full FuncMap (including datasource functions) is available.

type UniformQueryDistribution 

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

UniformQueryDistribution is a QueryDistribution that generates indices uniformly at random.

func NewUniformQueryDistribution 

func NewUniformQueryDistribution(n int) *UniformQueryDistribution

NewUniformQueryDistribution creates a new UniformQueryDistribution that generates indices in the range [0, n).

func (*UniformQueryDistribution) NextIndex 

func (u *UniformQueryDistribution) NextIndex() int

type UpsertLoad 

type UpsertLoad struct {
	NamespaceIndex int
	NumDocs        int
}

UpsertLoad is a tuple of a namespace index and the number of documents to upsert.

type UpsertWorkload 

type UpsertWorkload struct {
	Datasource       datasource.Kind `toml:"datasource,omitempty"`
	WPS              float64         `toml:"wps"`
	Concurrency      int             `toml:"concurrency,omitempty"`
	UpsertBatchSize  int             `toml:"upsert_batch_size,omitempty"`
	DocumentTemplate Template        `toml:"document_template"`
	UpsertTemplate   Template        `toml:"upsert_template"`
}

UpsertWorkload defines an upsert workload.

type Workloads 

type Workloads struct {
	Query  map[string]*QueryWorkload  `toml:"query"`
	Upsert map[string]*UpsertWorkload `toml:"upsert"`
}

Workloads matches TOML [workload.query.<name>] nested tables.

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.