---
title: ''
description: Telegraf plugin for aggregating metrics using Starlark
url: https://docs.influxdata.com/telegraf/v1/aggregator-plugins/starlark/
estimated_tokens: 1007
product: Telegraf Enterprise
version: v1
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/v1/aggregator-plugins/starlark/
date: '2026-05-21T20:10:18+02:00'
lastmod: '2026-05-21T20:10:18+02:00'
---

==========

* Telegraf v1.21.0+

[Plugin source](https://github.com/influxdata/telegraf/tree/v1.39.1/plugins/aggregators/starlark/)[Download configuration](https://raw.githubusercontent.com/influxdata/telegraf/refs/tags/v1.39.1/plugins/aggregators/starlark/sample.conf)

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

> [!Note]
> 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.