metricsgenerationprocessor

README

Metrics Generation Processor

Status
Stability	alpha: metrics
Distributions	contrib
Issues
Code Owners	@Aneurysm9

Status: under development; Not recommended for production usage.

Description

The metrics generation processor (metricsgenerationprocessor) can be used to create new metrics using existing metrics following a given rule. This processor currently supports the following two rule types for creating a new metric.

1. calculate: It can create a new metric from two existing metrics by applying one of the following arithmetic operations: add, subtract, multiply, divide, or percent. One use case is to calculate the pod.memory.utilization metric like the following equation- pod.memory.utilization = (pod.memory.usage.bytes / node.memory.limit)
2. scale: It can create a new metric by scaling the value of an existing metric with a given constant number. One use case is to convert pod.memory.usage metric values from Megabytes to Bytes (multiply the existing metric's value by 1,048,576)

calculate Rule Functionality

There are some specific behaviors of the calculate metric generation rule that users may want to be aware of:

• The created metric will have the same type as the metric configured as metric1.
• If no valid data points are calculated for the metric being created, it will not be created. This ensures the processor is not emitting new metrics that are empty.
• Users may want to have metric calculations done on data points whose overlapping attributes match. To enable this behavior, please enable the feature gate metricsgeneration.MatchAttributes. This feature gate is disabled by default, meaning the value used for metric2 during the calculations is simply the first data point's value. Refer to documentation for more information on how to enable and disable feature gates.

Configuration

Configuration is specified through a list of generation rules. Generation rules find the metrics which match the given metric names and apply the specified operation to those metrics.

processors:
    # processor name: metricsgeneration
    metricsgeneration:

        # specify the metric generation rules
        rules:
              # Name of the new metric. This is a required field.
            - name: <new_metric_name>

              # Unit for the new metric being generated.
              unit: <new_metric_unit>

              # type describes how the new metric will be generated. It can be one of `calculate` or `scale`.  calculate generates a metric applying the given operation on two operand metrics. scale operates only on operand1 metric to generate the new metric.
              type: {calculate, scale}

              # This is a required field. This must be a gauge or sum metric.
              metric1: <first_operand_metric>

              # This field is required only if the type is "calculate". When required, this must be a gauge or sum metric.
              metric2: <second_operand_metric>

              # Operation specifies which arithmetic operation to apply. It must be one of the five supported operations.
              operation: {add, subtract, multiply, divide, percent}

Example Configurations

Create a new metric using two existing metrics

# create pod.cpu.utilized following (pod.cpu.usage / node.cpu.limit)
rules:
    - name: pod.cpu.utilized
      type: calculate
      metric1: pod.cpu.usage
      metric2: node.cpu.limit
      operation: divide

Create a new metric scaling the value of an existing metric

# create pod.memory.usage.bytes from pod.memory.usage.megabytes
rules:
    - name: pod.memory.usage.bytes
      unit: Bytes
      type: scale
      metric1: pod.memory.usage.megabytes
      operation: multiply
      scale_by: 1048576

Documentation

Overview

package metricsgenerationprocessor implements a processor which calculates a new metric from existing metrics.

Index

• func NewFactory() processor.Factory
• type Config
  • func (config *Config) Validate() error
• type GenerationType
• type OperationType
• type Rule

Functions

func NewFactory

func NewFactory() processor.Factory

NewFactory returns a new factory for the Metrics Generation processor.

Types

type Config

type Config struct {
	// Set of rules for generating new metrics
	Rules []Rule `mapstructure:"rules"`
}

Config defines the configuration for the processor.

func (*Config) Validate

func (config *Config) Validate() error

Validate checks whether the input configuration has all of the required fields for the processor. An error is returned if there are any invalid inputs.

type GenerationType

type GenerationType string

type OperationType

type OperationType string

type Rule

type Rule struct {
	// Name of the new metric being generated. This is a required field.
	Name string `mapstructure:"name"`

	// Unit for the new metric being generated.
	Unit string `mapstructure:"unit"`

	// The rule type following which the new metric will be generated. This is a required field.
	Type GenerationType `mapstructure:"type"`

	// First operand metric to use in the calculation. This is a required field.
	Metric1 string `mapstructure:"metric1"`

	// Second operand metric to use in the calculation. A required field if the type is calculate.
	Metric2 string `mapstructure:"metric2"`

	// The arithmetic operation to apply for the calculation. This is a required field.
	Operation OperationType `mapstructure:"operation"`

	// A constant number by which the first operand will be scaled. A required field if the type is scale.
	ScaleBy float64 `mapstructure:"scale_by"`
}