| // 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 |
| // golang.org/x/perf/benchproc/syntax". |
| // |
| // 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 |
