Starlark Aggregator Plugin

This plugin allows to implement a custom aggregator plugin via a Starlark script.

The Starlark language is a dialect of Python and will be familiar to those who have experience with the Python language. However, there are major differences. Existing Python code is unlikely to work unmodified.

The Starlark script used by this plugin needs to be composed of the three methods defining an aggreagtor named add, push and reset.

The add method is called as soon as a new metric is added to the plugin the metrics to the aggregator. After period, the push method is called to output the resulting metrics and finally the aggregation is reset by using the reset method of the Starlark script.

The Starlark functions might use the global function state to keep aggregation information such as added metrics etc.

More details on the syntax and available functions can be found in the Starlark specification.

Introduced in: Telegraf v1.21.0 Tags: transformation OS support: all

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Configuration

# Aggregate metrics using a Starlark script
[[aggregators.starlark]]
  ## The Starlark source can be set as a string in this configuration file, or
  ## by referencing a file containing the script.  Only one source or script
  ## should be set at once.
  ##
  ## Source of the Starlark script.
  source = '''
state = {}

def add(metric):
  state["last"] = metric

def push():
  return state.get("last")

def reset():
  state.clear()
'''

  ## File containing a Starlark script.
  # script = "/usr/local/bin/myscript.star"

  ## The constants of the Starlark script.
  # [aggregators.starlark.constants]
  #   max_size = 10
  #   threshold = 0.75
  #   default_name = "Julia"
  #   debug_mode = true

Usage

The Starlark code should contain a function called add that takes a metric as argument. The function will be called with each metric to add, and doesn’t return anything.

def add(metric):
  state["last"] = metric

The Starlark code should also contain a function called push that doesn’t take any argument. The function will be called to compute the aggregation, and returns the metrics to push to the accumulator.

def push():
  return state.get("last")

The Starlark code should also contain a function called reset that doesn’t take any argument. The function will be called to reset the plugin, and doesn’t return anything.

def reset():
  state.clear()

For a list of available types and functions that can be used in the code, see the Starlark specification.

Python Differences

Refer to the section Python Differences of the documentation about the Starlark processor.

Libraries available

Refer to the section Libraries available of the documentation about the Starlark processor.

Common Questions

Refer to the section Common Questions of the documentation about the Starlark processor.

Examples

• minmax
• merge

All examples are in the testdata folder.

Open a Pull Request to add any other useful Starlark examples.