README
¶
Starlark Aggregator Plugin
The starlark aggregator allows to implement a custom aggregator plugin with a
Starlark script. The Starlark script needs to be composed of the three methods
defined in the Aggregator plugin interface which are add, push and reset.
The Starlark Aggregator plugin calls the Starlark function add to add the
metrics to the aggregator, then calls the Starlark function push to push the
resulting metrics into the accumulator and finally calls the Starlark function
reset to reset the entire state of the plugin.
The Starlark functions can use the global function state to keep temporary the
metrics to aggregate.
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 execution environment is sandboxed, and it is not possible to do I/O operations such as reading from files or sockets.
The Starlark specification has details about the syntax and available functions.
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 - A minmax aggregator implemented with a Starlark script.
- merge - A merge aggregator implemented with a Starlark script.
All examples are in the testdata folder.
Open a Pull Request to add any other useful Starlark examples.
Documentation
Source Files