---
title: Telegraf Documentation
description: Telegraf plugin for aggregating metrics using Starlark
url: https://docs.influxdata.com/telegraf/v1/aggregator-plugins/starlark/
estimated_tokens: 2069
product: Telegraf
version: v1
---

-   Telegraf v1.21.0+

# Starlark Aggregator Plugin

This plugin allows to implement a custom aggregator plugin via a [Starlark](https://github.com/google/starlark-go) 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 execution environment is sandboxed, and it is not possible to access the local filesystem or perfoming network operations. This is by design of the Starlark language as a configuration language.

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](https://github.com/google/starlark-go/blob/d1966c6b9fcd/doc/spec.md).

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

## Global configuration options

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details.

## Configuration

```toml
# 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.

```python
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.

```python
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.

```python
def reset():
  state.clear()
```

For a list of available types and functions that can be used in the code, see the [Starlark specification](https://github.com/google/starlark-go/blob/d1966c6b9fcd/doc/spec.md).

## 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.

#### Related

-   [Configure plugins](/telegraf/v1/configure_plugins/)
-   [Starlark Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/aggregators/starlark/README.md)