blob: 7c3a0352be57b8cbeb191771785c847c0e443705 [file] [log] [blame]
// Copyright 2022 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package benchproc provides tools for filtering, grouping, and
// sorting benchmark results.
// This package supports a pipeline processing model based around
// domain-specific languages for filtering and projecting benchmark
// results. These languages are described in "go doc
// The typical steps for processing a stream of benchmark
// results are:
// 1. Read a stream of benchfmt.Results from one or more input sources.
// Command-line tools will often do this using benchfmt.Files.
// 2. For each benchfmt.Result:
// 2a. Optionally transform the benchfmt.Result to add or modify keys
// according to a particular tool's needs. Custom keys often start with
// "." to distinguish them from file or sub-name keys. For example,
// benchfmt.Files adds a ".file" key.
// 2b. Optionally filter the benchfmt.Result according to a user-provided
// predicate parsed by NewFilter. Filters can keep or discard entire
// Results, or just particular measurements from a Result.
// 2c. Project the benchfmt.Result using one or more Projections.
// Projecting a Result extracts a subset of the information from a
// Result into a Key. Projections are produced by a ProjectionParser,
// typically from user-provided projection expressions. An application
// should have a Projection for each "dimension" of its output. For
// example, an application that emits a table may have two Projections:
// one for rows and one for columns. An application that produces a
// scatterplot could have Projections for X and Y as well as other
// visual properties like point color and size.
// 2d. Group the benchfmt.Result according to the projected Keys.
// Usually this is done by storing the measurements from the Result in a
// Go map indexed by Key. Because identical Keys compare ==, they can be
// used as map keys. Applications that use two or more Projections may
// use a map of maps, or a map keyed by a struct of two Keys, or some
// combination.
// 3. At the end of the Results stream, once all Results have been
// grouped by their Keys, sort the Keys of each dimension using SortKeys
// and present the data in the resulting order.
package benchproc