Dagger
Search

bench

stage is a container whose evaluation is the work to measure. Stages are
accumulated with WithStage and run either sequentially (isolated timings) or
concurrently (real-world full-pipeline wall-clock).

A stage is a container rather than a callback so the harness can be shared
across projects: containers cross Dagger module boundaries, closures do not.
Cache-busting belongs in the stage container (applied before the work, e.g.
via the go toolchain's CacheBust) -- this harness only evaluates and times.

Installation

dagger install github.com/MacroPower/x/toolchains/bench@3f4ef26289cf6c0690d4ce596cd8832b729b8ad4

Entrypoint

Return Type 
Bench !
Example
dagger -m github.com/MacroPower/x/toolchains/bench@3f4ef26289cf6c0690d4ce596cd8832b729b8ad4 call \

func (m *MyModule) Example() *dagger.Bench  {
	return dag.
			Bench()
}
@function
def example() -> dagger.Bench:
	return (
		dag.bench()
	)
@func()
example(): Bench {
	return dag
		.bench()
}

Types

Bench 🔗

Bench accumulates named container stages to time. Create instances with [New] and add stages with [Bench.WithStage].

run() 🔗

Run evaluates each stage and returns its timing. When parallel is false, stages run one at a time for isolated timings; when true, concurrently to measure full-pipeline wall-clock time. A failing stage is recorded (Ok=false) rather than aborting the run.

Return Type 
[Result ! ] !
Arguments
NameTypeDefault ValueDescription
parallelBoolean !falseRun stages concurrently instead of sequentially.
Example
dagger -m github.com/MacroPower/x/toolchains/bench@3f4ef26289cf6c0690d4ce596cd8832b729b8ad4 call \
 run --parallel boolean
func (m *MyModule) Example(parallel bool) []*dagger.BenchResult  {
	return dag.
			Bench().
			Run(parallel)
}
@function
def example(parallel: bool) -> List[dagger.BenchResult]:
	return (
		dag.bench()
		.run(parallel)
	)
@func()
example(parallel: boolean): BenchResult[] {
	return dag
		.bench()
		.run(parallel)
}

summary() 🔗

Summary runs the stages and returns an aligned text table, a convenience wrapper around [Bench.Run] for CLI use without jq post-processing.

Return Type 
String !
Arguments
NameTypeDefault ValueDescription
parallelBoolean !falseRun stages concurrently instead of sequentially.
Example
dagger -m github.com/MacroPower/x/toolchains/bench@3f4ef26289cf6c0690d4ce596cd8832b729b8ad4 call \
 summary --parallel boolean
func (m *MyModule) Example(ctx context.Context, parallel bool) string  {
	return dag.
			Bench().
			Summary(ctx, parallel)
}
@function
async def example(parallel: bool) -> str:
	return await (
		dag.bench()
		.summary(parallel)
	)
@func()
async example(parallel: boolean): Promise<string> {
	return dag
		.bench()
		.summary(parallel)
}

withStage() 🔗

WithStage adds a named stage to time. The container should be fully built up to the point that evaluating it performs the work to measure (including any cache-busting); [Bench.Run] calls Sync on it and records the duration.

Return Type 
Bench !
Arguments
NameTypeDefault ValueDescription
nameString !-Stage name (e.g. "lint", "test").
ctrContainer !-Container whose evaluation is the work to time.
Example
dagger -m github.com/MacroPower/x/toolchains/bench@3f4ef26289cf6c0690d4ce596cd8832b729b8ad4 call \
 with-stage --name string --ctr IMAGE:TAG
func (m *MyModule) Example(name string, ctr *dagger.Container) *dagger.Bench  {
	return dag.
			Bench().
			WithStage(name, ctr)
}
@function
def example(name: str, ctr: dagger.Container) -> dagger.Bench:
	return (
		dag.bench()
		.with_stage(name, ctr)
	)
@func()
example(name: string, ctr: Container): Bench {
	return dag
		.bench()
		.withStage(name, ctr)
}

Result 🔗

Result holds the timing for a single stage.

name() 🔗

Stage name.

Return Type 
String !
Example
Function BenchResult.name is not accessible from the bench module
Function BenchResult.name is not accessible from the bench module
Function BenchResult.name is not accessible from the bench module
Function BenchResult.name is not accessible from the bench module

durationSecs() 🔗

Wall-clock duration in seconds.

Return Type 
Float !
Example
Function BenchResult.durationSecs is not accessible from the bench module
Function BenchResult.durationSecs is not accessible from the bench module
Function BenchResult.durationSecs is not accessible from the bench module
Function BenchResult.durationSecs is not accessible from the bench module

ok() 🔗

Whether the stage completed successfully.

Return Type 
Boolean !
Example
Function BenchResult.ok is not accessible from the bench module
Function BenchResult.ok is not accessible from the bench module
Function BenchResult.ok is not accessible from the bench module
Function BenchResult.ok is not accessible from the bench module

error() 🔗

Error message if the stage failed.

Return Type 
String !
Example
Function BenchResult.error is not accessible from the bench module
Function BenchResult.error is not accessible from the bench module
Function BenchResult.error is not accessible from the bench module
Function BenchResult.error is not accessible from the bench module