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