github.com/jgbaldwinbrown/perf@v0.1.1/benchproc/doc.go (about) 1 // Copyright 2022 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package benchproc provides tools for filtering, grouping, and 6 // sorting benchmark results. 7 // 8 // This package supports a pipeline processing model based around 9 // domain-specific languages for filtering and projecting benchmark 10 // results. These languages are described in "go doc 11 // golang.org/x/perf/benchproc/syntax". 12 // 13 // The typical steps for processing a stream of benchmark 14 // results are: 15 // 16 // 1. Read a stream of benchfmt.Results from one or more input sources. 17 // Command-line tools will often do this using benchfmt.Files. 18 // 19 // 2. For each benchfmt.Result: 20 // 21 // 2a. Optionally transform the benchfmt.Result to add or modify keys 22 // according to a particular tool's needs. Custom keys often start with 23 // "." to distinguish them from file or sub-name keys. For example, 24 // benchfmt.Files adds a ".file" key. 25 // 26 // 2b. Optionally filter the benchfmt.Result according to a user-provided 27 // predicate parsed by NewFilter. Filters can keep or discard entire 28 // Results, or just particular measurements from a Result. 29 // 30 // 2c. Project the benchfmt.Result using one or more Projections. 31 // Projecting a Result extracts a subset of the information from a 32 // Result into a Key. Projections are produced by a ProjectionParser, 33 // typically from user-provided projection expressions. An application 34 // should have a Projection for each "dimension" of its output. For 35 // example, an application that emits a table may have two Projections: 36 // one for rows and one for columns. An application that produces a 37 // scatterplot could have Projections for X and Y as well as other 38 // visual properties like point color and size. 39 // 40 // 2d. Group the benchfmt.Result according to the projected Keys. 41 // Usually this is done by storing the measurements from the Result in a 42 // Go map indexed by Key. Because identical Keys compare ==, they can be 43 // used as map keys. Applications that use two or more Projections may 44 // use a map of maps, or a map keyed by a struct of two Keys, or some 45 // combination. 46 // 47 // 3. At the end of the Results stream, once all Results have been 48 // grouped by their Keys, sort the Keys of each dimension using SortKeys 49 // and present the data in the resulting order. 50 package benchproc