CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Edit Starlark README (#7832)

This commit is contained in:
pierwill 2020-07-14 16:05:22 -07:00 committed by GitHub
parent 3ec3f1bc50
commit f9b4138758
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
plugins/processors/starlark/README.md
View File

@ -4,8 +4,7 @@ The `starlark` processor calls a Starlark function for each matched metric,
allowing for custom programmatic metric processing. allowing for custom programmatic metric processing.
The Starlark language is a dialect of Python, and will be familiar to those who The Starlark language is a dialect of Python, and will be familiar to those who
have experience with the Python language. However, keep in mind that it is not have experience with the Python language. However, there are major [differences](#python-differences).
Python and that there are major syntax [differences][#Python Differences].
Existing Python code is unlikely to work unmodified. The execution environment 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 is sandboxed, and it is not possible to do I/O operations such as reading from
files or sockets. files or sockets.
@ -22,7 +21,7 @@ Telegraf minimum version: Telegraf 1.15.0
## The Starlark source can be set as a string in this configuration file, or ## 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 ## by referencing a file containing the script. Only one source or script
## should be set at once. ## should be set at once.
##
## Source of the Starlark script. ## Source of the Starlark script.
source = ''' source = '''
def apply(metric): def apply(metric):
@ -35,29 +34,31 @@ def apply(metric):
### Usage ### Usage
The script should contain a function called `apply` that takes the metric as 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 its single argument. The function will be called with each metric, and can
return `None`, a single metric, or a list of metrics. return `None`, a single metric, or a list of metrics.
```python ```python
def apply(metric): def apply(metric):
return metric return metric
``` ```
Reference the Starlark [specification][] to see the list of available types and For a list of available types and functions that can be used in the code, see
functions that can be used in the script. In addition to these the following the Starlark [specification][].
In addition to these, the following InfluxDB-specific
types and functions are exposed to the script. types and functions are exposed to the script.
**Metric(*name*)**: - **Metric(*name*)**:
Create a new metric with the given measurement name. The metric will have no Create a new metric with the given measurement name. The metric will have no
tags or fields and defaults to the current time. tags or fields and defaults to the current time.
- **name**: - **name**:
The name is a [string][string] containing the metric measurement name. The name is a [string][] containing the metric measurement name.
- **tags**: - **tags**:
A [dict-like][dict] object containing the metric's tags. A [dict-like][dict] object containing the metric's tags.
- **fields**: - **fields**:
A [dict-like][dict] object containing the metric's fields. The values may be A [dict-like][dict] object containing the metric's fields. The values may be
of type int, float, string, or bool. of type int, float, string, or bool.
@ -66,18 +67,20 @@ of type int, float, string, or bool.
The timestamp of the metric as an integer in nanoseconds since the Unix The timestamp of the metric as an integer in nanoseconds since the Unix
epoch. epoch.
**deepcopy(*metric*)**: Make a copy of an existing metric. - **deepcopy(*metric*)**: Make a copy of an existing metric.
### Python Differences ### Python Differences
While Starlark is similar to Python it is not the same. While Starlark is similar to Python, there are important differences to note:
- Starlark has limited support for error handling and no exceptions. If an - Starlark has limited support for error handling and no exceptions. If an
error occurs the script will immediately end and Telegraf will drop the error occurs the script will immediately end and Telegraf will drop the
metric. Check the Telegraf logfile for details about the error. metric. Check the Telegraf logfile for details about the error.
- It is not possible to import other packages and the Python standard library - It is not possible to import other packages and the Python standard library
is not available. As such, it is not possible to open files or sockets. is not available.
- It is not possible to open files or sockets.
- These common keywords are **not supported** in the Starlark grammar: - These common keywords are **not supported** in the Starlark grammar:
``` ```
@ -102,6 +105,7 @@ Use `deepcopy(metric)` to create a copy of the metric.
**How can I return multiple metrics?** **How can I return multiple metrics?**
You can return a list of metrics: You can return a list of metrics:
```python ```python
def apply(metric): def apply(metric):
m2 = deepcopy(metric) m2 = deepcopy(metric)
@ -119,6 +123,7 @@ Use the `Metric(name)` function and set at least one field.
**What is the fastest way to iterate over tags/fields?** **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: The fastest way to iterate is to use a for-loop on the tags or fields attribute:
```python ```python
def apply(metric): def apply(metric):
for k in metric.tags: for k in metric.tags:
@ -127,7 +132,8 @@ def apply(metric):
``` ```
When you use this form, it is not possible to modify the tags inside the loop, When you use this form, it is not possible to modify the tags inside the loop,
if this is needed you should use the `.keys()`, `.values()`, or `.items()` forms: if this is needed you should use one of the `.keys()`, `.values()`, or `.items()` methods:
```python ```python
def apply(metric): def apply(metric):
for k, v in metric.tags.items(): for k, v in metric.tags.items():