Show how to return several metrics with the Starlark processor

plugins/processors/starlark/README.md

@@ -187,6 +187,8 @@ def failing(metric):
 - [scale](/plugins/processors/starlark/testdata/scale.star) - Multiply any field by a number
 - [value filter](/plugins/processors/starlark/testdata/value_filter.star) - remove a metric based on a field value.
 - [logging](/plugins/processors/starlark/testdata/logging.star) - Log messages with the logger of Telegraf
+- [multiple metrics](/plugins/processors/starlark/testdata/multiple_metrics.star) - Return multiple metrics by using [a list](https://docs.bazel.build/versions/master/skylark/lib/list.html) of metrics.
+- [multiple metrics from json array](/plugins/processors/starlark/testdata/multiple_metrics_with_json.star) - Builds a new metric from each element of a json array then returns all the created metrics.
 
 [All examples](/plugins/processors/starlark/testdata) are in the testdata folder.
 

plugins/processors/starlark/starlark_test.go

@@ -2560,6 +2560,70 @@ func TestScript(t *testing.T) {
 				),
 			},
 		},
+		{
+			name: "multiple_metrics",
+			plugin: &Starlark{
+				Script: "testdata/multiple_metrics.star",
+				Log:    testutil.Logger{},
+			},
+			input: []telegraf.Metric{
+				testutil.MustMetric("mm",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "a",
+					},
+					time.Unix(0, 0),
+				),
+			},
+			expected: []telegraf.Metric{
+				testutil.MustMetric("mm2",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "b",
+					},
+					time.Unix(0, 0),
+				),
+				testutil.MustMetric("mm1",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "a",
+					},
+					time.Unix(0, 0),
+				),
+			},
+		},
+		{
+			name: "multiple_metrics_with_json",
+			plugin: &Starlark{
+				Script: "testdata/multiple_metrics_with_json.star",
+				Log:    testutil.Logger{},
+			},
+			input: []telegraf.Metric{
+				testutil.MustMetric("json",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "[{\"label\": \"hello\"}, {\"label\": \"world\"}]",
+					},
+					time.Unix(0, 0),
+				),
+			},
+			expected: []telegraf.Metric{
+				testutil.MustMetric("json",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "hello",
+					},
+					time.Unix(0, 0),
+				),
+				testutil.MustMetric("json",
+					map[string]string{},
+					map[string]interface{}{
+						"value": "world",
+					},
+					time.Unix(0, 0),
+				),
+			},
+		},
 	}
 
 	for _, tt := range tests {

plugins/processors/starlark/testdata/multiple_metrics.star

@@ -0,0 +1,26 @@
+# Example showing how to create several metrics using the Starlark processor.
+#
+# Example Input:
+# mm value="a" 1465839830100400201
+#
+# Example Output:
+# mm2 value="b" 1465839830100400201
+# mm1 value="a" 1465839830100400201
+
+def apply(metric):
+    # Initialize a list of metrics
+    metrics = []
+    # Create a new metric whose name is "mm2"
+    metric2 = Metric("mm2")
+    # Set the field "value" to b
+    metric2.fields["value"] = "b"
+    # Reset the time (only needed for testing purpose)
+    metric2.time = 0
+    # Add metric2 to the list of metrics
+    metrics.append(metric2)
+    # Rename the original metric to "mm1"
+    metric.name = "mm1"
+    # Add metric to the list of metrics
+    metrics.append(metric)    
+    # Return the created list of metrics
+    return metrics

plugins/processors/starlark/testdata/multiple_metrics_with_json.star

@@ -0,0 +1,26 @@
+# Example showing how to create several metrics from a json array.
+#
+# Example Input:
+# json value="[{\"label\": \"hello\"}, {\"label\": \"world\"}]"
+#
+# Example Output:
+# json value="hello" 1465839830100400201
+# json value="world" 1465839830100400201
+
+# loads json.encode(), json.decode(), json.indent()
+load("json.star", "json")
+
+def apply(metric):
+    # Initialize a list of metrics
+    metrics = []
+    # Loop over the json array stored into the field 
+    for obj in json.decode(metric.fields['value']):
+        # Create a new metric whose name is "json"
+        current_metric = Metric("json")
+        # Set the field "value" to the label extracted from the current json object
+        current_metric.fields["value"] = obj["label"]
+        # Reset the time (only needed for testing purpose)
+        current_metric.time = 0
+        # Add metric to the list of metrics
+        metrics.append(current_metric)
+    return metrics