README
¶
Starlark Processor
The starlark processor calls a Starlark function for each matched metric,
allowing for custom programmatic metric processing.
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.
Telegraf minimum version: Telegraf 1.15.0
Configuration
[[processors.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 = '''
def apply(metric):
return metric
'''
## File containing a Starlark script.
# script = "/usr/local/bin/myscript.star"
Usage
The Starlark code should contain a function called apply that takes a metric as
its single argument. The function will be called with each metric, and can
return None, a single metric, or a list of metrics.
def apply(metric):
return metric
For a list of available types and functions that can be used in the code, see the Starlark specification.
In addition to these, the following InfluxDB-specific types and functions are exposed to the script.
-
Metric(name): Create a new metric with the given measurement name. The metric will have no tags or fields and defaults to the current time.
-
name: The name is a string containing the metric measurement name.
-
tags: A dict-like object containing the metric's tags.
-
fields: A dict-like object containing the metric's fields. The values may be of type int, float, string, or bool.
-
time: The timestamp of the metric as an integer in nanoseconds since the Unix epoch.
-
deepcopy(metric): Make a copy of an existing metric.
Python Differences
While Starlark is similar to Python, there are important differences to note:
-
Starlark has limited support for error handling and no exceptions. If an error occurs the script will immediately end and Telegraf will drop the metric. Check the Telegraf logfile for details about the error.
-
It is not possible to import other packages and the Python standard library is not available.
-
It is not possible to open files or sockets.
-
These common keywords are not supported in the Starlark grammar:
as finally nonlocal assert from raise class global try del import with except is yield
Common Questions
How can I drop/delete a metric?
If you don't return the metric it will be deleted. Usually this means the
function should return None.
How should I make a copy of a metric?
Use deepcopy(metric) to create a copy of the metric.
How can I return multiple metrics?
You can return a list of metrics:
def apply(metric):
m2 = deepcopy(metric)
return [metric, m2]
What happens to a tracking metric if an error occurs in the script?
The metric is marked as undelivered.
How do I create a new metric?
Use the Metric(name) function and set at least one field.
What is the fastest way to iterate over tags/fields?
The fastest way to iterate is to use a for-loop on the tags or fields attribute:
def apply(metric):
for k in metric.tags:
pass
return metric
When you use this form, it is not possible to modify the tags inside the loop,
if this is needed you should use one of the .keys(), .values(), or .items() methods:
def apply(metric):
for k, v in metric.tags.items():
pass
return metric
How can I save values across multiple calls to the script?
Telegraf freezes the global scope, which prevents it from being modified. Attempting to modify the global scope will fail with an error.
Examples
Open a PR to add any other useful Starlark examples.
Documentation
¶
Index ¶
- Variables
- type FieldDict
- func (d FieldDict) Attr(name string) (starlark.Value, error)
- func (d FieldDict) AttrNames() []string
- func (d FieldDict) Clear() error
- func (d FieldDict) Delete(k starlark.Value) (v starlark.Value, found bool, err error)
- func (d FieldDict) Freeze()
- func (d FieldDict) Get(key starlark.Value) (v starlark.Value, found bool, err error)
- func (d FieldDict) Hash() (uint32, error)
- func (d FieldDict) Items() []starlark.Tuple
- func (d FieldDict) Iterate() starlark.Iterator
- func (d FieldDict) PopItem() (v starlark.Value, err error)
- func (d FieldDict) SetKey(k, v starlark.Value) error
- func (d FieldDict) String() string
- func (d FieldDict) Truth() starlark.Bool
- func (d FieldDict) Type() string
- type FieldIterator
- type Metric
- func (m *Metric) Attr(name string) (starlark.Value, error)
- func (m *Metric) AttrNames() []string
- func (m *Metric) Fields() FieldDict
- func (m *Metric) Freeze()
- func (m *Metric) Hash() (uint32, error)
- func (m *Metric) Name() starlark.String
- func (m *Metric) SetField(name string, value starlark.Value) error
- func (m *Metric) SetName(value starlark.Value) error
- func (m *Metric) SetTime(value starlark.Value) error
- func (m *Metric) String() string
- func (m *Metric) Tags() TagDict
- func (m *Metric) Time() starlark.Int
- func (m *Metric) Truth() starlark.Bool
- func (m *Metric) Type() string
- func (m *Metric) Unwrap() telegraf.Metric
- func (m *Metric) Wrap(metric telegraf.Metric)
- type Starlark
- type TagDict
- func (d TagDict) Attr(name string) (starlark.Value, error)
- func (d TagDict) AttrNames() []string
- func (d TagDict) Clear() error
- func (d TagDict) Delete(k starlark.Value) (v starlark.Value, found bool, err error)
- func (d TagDict) Freeze()
- func (d TagDict) Get(key starlark.Value) (v starlark.Value, found bool, err error)
- func (d TagDict) Hash() (uint32, error)
- func (d TagDict) Items() []starlark.Tuple
- func (d TagDict) Iterate() starlark.Iterator
- func (d TagDict) PopItem() (v starlark.Value, err error)
- func (d TagDict) SetKey(k, v starlark.Value) error
- func (d TagDict) String() string
- func (d TagDict) Truth() starlark.Bool
- func (d TagDict) Type() string
- type TagIterator
Constants ¶
This section is empty.
Variables ¶
var FieldDictMethods = map[string]builtinMethod{
"clear": dict_clear,
"get": dict_get,
"items": dict_items,
"keys": dict_keys,
"pop": dict_pop,
"popitem": dict_popitem,
"setdefault": dict_setdefault,
"update": dict_update,
"values": dict_values,
}
var TagDictMethods = map[string]builtinMethod{
"clear": dict_clear,
"get": dict_get,
"items": dict_items,
"keys": dict_keys,
"pop": dict_pop,
"popitem": dict_popitem,
"setdefault": dict_setdefault,
"update": dict_update,
"values": dict_values,
}
Functions ¶
This section is empty.
Types ¶
type FieldDict ¶
type FieldDict struct {
*Metric
}
FieldDict is a starlark.Value for the metric fields. It is heavily based on the starlark.Dict.
type FieldIterator ¶
type FieldIterator struct {
*Metric
// contains filtered or unexported fields
}
func (*FieldIterator) Done ¶
func (i *FieldIterator) Done()
Done implements the starlark.Iterator interface.
type Metric ¶
type Metric struct {
// contains filtered or unexported fields
}
func (*Metric) String ¶
String returns the starlark representation of the Metric.
The String function is called by both the repr() and str() functions, and so it behaves more like the repr function would in Python.
type Starlark ¶
type Starlark struct {
Source string `toml:"source"`
Script string `toml:"script"`
Log telegraf.Logger `toml:"-"`
// contains filtered or unexported fields
}
func (*Starlark) Description ¶
func (*Starlark) SampleConfig ¶
type TagDict ¶
type TagDict struct {
*Metric
}
TagDict is a starlark.Value for the metric tags. It is heavily based on the starlark.Dict.
type TagIterator ¶
type TagIterator struct {
*Metric
// contains filtered or unexported fields
}
func (*TagIterator) Done ¶
func (i *TagIterator) Done()
Done implements the starlark.Iterator interface.
Source Files