go_benchpress

README

Go Benchpress

Go Benchpress is a visualisation utility for comparing the results of benchmarks.

Benchmarks are a really useful tool for comparing a couple of different strategies for achieving a goal, but also for an easy understanding of performance regressions within the system.

Sub-benchmarks are particularly useful for understanding how a particular feature operates over different data-set sizes.

Go Benchpress simplifies visualising these benchmark results - designed particularly for sub-benchmarks and demonstrating how your code performs at different data-set sizes - visually.

What Is Output?

Go Benchpress outputs, by default, a file of results for each benchmark passed in (via the Benchmark result data).

This is so that sub-benchmarks can be compared more easily.

A second mode of operation exists - 'no separation'. This is where the results of all the passed in benchmarks are output into a single file.

You will find more information on the specifics of this in the CSV Parser package - the README contains details instructions on CLI usage, and how to make use of these different modes.

So, given Go Benchpress will either output a file for each benchmark, or a single file for all benchmarks, what formats are available?

What Does It Look Like?

Go Benchpress output can look like a variety of things.

Graphically, this is what a Go Benchpress output looks like:

As you can see, it compares all the results for a single benchmark (across its various sub-benchmarks), displaying their relative values visually.

You can choose between several dimensions (including nanoseconds per operation, bytes per operation, etc.) - for the most recent advice on this, please consult the help text using:

gobenchpress -help

There are also other formats to choose from - overall the following formats are supported:

1. SVG (as a bar chart)
2. PNG (as a bar chart)
3. JSON
4. CSV
5. XML

See the example CSV Parser package for instructions on how to use different formats, and what they look like.

How to Install?

Run the following command at a terminal:

go get github.com/rpickz/go-benchpress/cmd/gobenchpress

How to Use?

See the example CSV Parser package for instructions on how to use.

For more detailed instructions, see the CLI usage info with the following:

gobenchpress -help

License?

MIT License.

Documentation

Index

• Variables
• func ReadBenchmarks(reader io.Reader) ([]parse.Benchmark, error)
• type BenchmarkSets
  • func ReadAndSeparateBenchmarks(reader io.Reader) (BenchmarkSets, error)
• type CSVRenderer
  • func (c *CSVRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, ...) error
• type JSONRenderer
  • func (j *JSONRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, ...) error
• type RasterRenderer
  • func NewRasterRenderer(title string, renderType RenderType) *RasterRenderer
  • func (r *RasterRenderer) Render(writer io.Writer, parentBenchmark string, renderDimension RenderDimension, ...) error
• type RenderDimension
  • func RenderDimensionFromString(str string) (RenderDimension, error)
  • func (r RenderDimension) String() string
• type RenderType
  • func RenderTypeFromString(str string) (RenderType, error)
  • func (r RenderType) FileExtension() string
  • func (r RenderType) Renderer(title string) (Renderer, error)
  • func (r RenderType) String() string
• type Renderer
• type XMLRenderer
  • func (x *XMLRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, ...) error

Variables

var (
	ErrNoBenchmarksProvided = errors.New("could not render benchmarks - no benchmarks provided")
	ErrUnknownRenderType    = errors.New("unknown render type")
	ErrCouldNotParseLine    = errors.New("could not parse benchmark line")
	ErrUnknownDimensionType = errors.New("unknown render dimension type")
)

Functions

func ReadBenchmarks

func ReadBenchmarks(reader io.Reader) ([]parse.Benchmark, error)

ReadBenchmarks uses the provided reader, and reads the benchmarks from the read lines. If lines cannot be read, or parsed, an error is returned.

Types

type BenchmarkSets

type BenchmarkSets map[string][]parse.Benchmark

BenchmarkSets represents a number of benchmarks, grouped by the parent benchmark.

func ReadAndSeparateBenchmarks

func ReadAndSeparateBenchmarks(reader io.Reader) (BenchmarkSets, error)

ReadAndSeparateBenchmarks reads benchmarks from the provided reader, and groups them by benchmark name (which is split from sub-benchmark names). If the operation did not succeed, an error is returned.

type CSVRenderer

type CSVRenderer struct {
}

func (*CSVRenderer) Render

func (c *CSVRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, benchmarks []parse.Benchmark) error

type JSONRenderer

type JSONRenderer struct {
}

func (*JSONRenderer) Render

func (j *JSONRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, benchmarks []parse.Benchmark) error

type RasterRenderer

type RasterRenderer struct {
	Title      string
	Height     int
	BarWidth   int
	RenderType RenderType
	// contains filtered or unexported fields
}

RasterRenderer outputs a raster graphic based representation of the benchmarks, compared against one another.

func NewRasterRenderer

func NewRasterRenderer(title string, renderType RenderType) *RasterRenderer

func (*RasterRenderer) Render

func (r *RasterRenderer) Render(writer io.Writer, parentBenchmark string, renderDimension RenderDimension, benchmarks []parse.Benchmark) error

type RenderDimension

type RenderDimension int

const (
	RenderNsPerOp RenderDimension = iota
	RenderBytesPerOp
	RenderAllocsPerOp
)

func RenderDimensionFromString

func RenderDimensionFromString(str string) (RenderDimension, error)

func (RenderDimension) String

func (r RenderDimension) String() string

type RenderType

type RenderType int

const (
	PNG RenderType = iota
	SVG
	JSON
	CSV
	XML
)

func RenderTypeFromString

func RenderTypeFromString(str string) (RenderType, error)

func (RenderType) FileExtension

func (r RenderType) FileExtension() string

func (RenderType) Renderer

func (r RenderType) Renderer(title string) (Renderer, error)

Renderer provides an instance of a Renderer for the RenderType - for instance, a JSONRenderer for JSON. If there is no matching Renderer for the RenderType, an ErrUnknownRenderType is returned.

func (RenderType) String

func (r RenderType) String() string

type Renderer

type Renderer interface {
	Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, benchmarks []parse.Benchmark) error
}

type XMLRenderer

type XMLRenderer struct {
}

func (*XMLRenderer) Render

func (x *XMLRenderer) Render(writer io.Writer, parentBenchmark string, dimension RenderDimension, benchmarks []parse.Benchmark) error