github.com/go-graphite/carbonapi@v0.17.0/expr/functions/consolidateBy/function.go (about)

     1  package consolidateBy
     2  
     3  import (
     4  	"context"
     5  
     6  	"github.com/go-graphite/carbonapi/expr/consolidations"
     7  	"github.com/go-graphite/carbonapi/expr/helper"
     8  	"github.com/go-graphite/carbonapi/expr/interfaces"
     9  	"github.com/go-graphite/carbonapi/expr/types"
    10  	"github.com/go-graphite/carbonapi/pkg/parser"
    11  )
    12  
    13  type consolidateBy struct{}
    14  
    15  func GetOrder() interfaces.Order {
    16  	return interfaces.Any
    17  }
    18  
    19  func New(configFile string) []interfaces.FunctionMetadata {
    20  	res := make([]interfaces.FunctionMetadata, 0)
    21  	f := &consolidateBy{}
    22  	functions := []string{"consolidateBy"}
    23  	for _, n := range functions {
    24  		res = append(res, interfaces.FunctionMetadata{Name: n, F: f})
    25  	}
    26  	return res
    27  }
    28  
    29  // The set of valid aggregation methods for consolidateBy function.
    30  var ValidAggregateFunctions = map[string]struct{}{
    31  	"average": {},
    32  	"avg":     {},
    33  	"max":     {},
    34  	"min":     {},
    35  	"sum":     {},
    36  	"first":   {},
    37  	"last":    {},
    38  }
    39  
    40  // consolidateBy(seriesList, aggregationMethod)
    41  func (f *consolidateBy) Do(ctx context.Context, eval interfaces.Evaluator, e parser.Expr, from, until int64, values map[parser.MetricRequest][]*types.MetricData) ([]*types.MetricData, error) {
    42  	if e.ArgsLen() < 2 {
    43  		return nil, parser.ErrMissingArgument
    44  	}
    45  
    46  	arg, err := helper.GetSeriesArg(ctx, eval, e.Arg(0), from, until, values)
    47  	if err != nil {
    48  		return nil, err
    49  	}
    50  	name, err := e.GetStringArg(1)
    51  	if err != nil {
    52  		return nil, err
    53  	}
    54  
    55  	results := make([]*types.MetricData, len(arg))
    56  
    57  	for i, a := range arg {
    58  		r := a.CopyLink()
    59  		r.Name = "consolidateBy(" + a.Name + ",\"" + name + "\")"
    60  		r.ConsolidationFunc = name
    61  		r.Tags["consolidateBy"] = name
    62  		results[i] = r
    63  	}
    64  
    65  	return results, nil
    66  }
    67  
    68  // Description is auto-generated description, based on output of https://github.com/graphite-project/graphite-web
    69  func (f *consolidateBy) Description() map[string]types.FunctionDescription {
    70  	return map[string]types.FunctionDescription{
    71  		"consolidateBy": {
    72  			Description: "Takes one metric or a wildcard seriesList and a consolidation function name.\n\nValid function names are 'sum', 'average', 'min', 'max', 'first' & 'last'.\n\nWhen a graph is drawn where width of the graph size in pixels is smaller than\nthe number of datapoints to be graphed, Graphite consolidates the values to\nto prevent line overlap. The consolidateBy() function changes the consolidation\nfunction from the default of 'average' to one of 'sum', 'max', 'min', 'first', or 'last'.\nThis is especially useful in sales graphs, where fractional values make no sense and a 'sum'\nof consolidated values is appropriate.\n\n.. code-block:: none\n\n  &target=consolidateBy(Sales.widgets.largeBlue, 'sum')\n  &target=consolidateBy(Servers.web01.sda1.free_space, 'max')",
    73  			Function:    "consolidateBy(seriesList, consolidationFunc)",
    74  			Group:       "Special",
    75  			Module:      "graphite.render.functions",
    76  			Name:        "consolidateBy",
    77  			Params: []types.FunctionParam{
    78  				{
    79  					Name:     "seriesList",
    80  					Required: true,
    81  					Type:     types.SeriesList,
    82  				},
    83  				{
    84  					Name:     "consolidationFunc",
    85  					Options:  types.StringsToSuggestionList(consolidations.AvailableConsolidationFuncs()),
    86  					Required: true,
    87  					Type:     types.String,
    88  				},
    89  			},
    90  		},
    91  	}
    92  }