From 73ae40235da14d9ff384a9f6a4b0a45f997099a3 Mon Sep 17 00:00:00 2001
From: Mya <myalongmire05@gmail.com>
Date: Tue, 5 Jul 2022 11:27:19 -0600
Subject: [PATCH] docs(inputs.mqtt_consumer): add pivot example to readme
 (#11195)

(cherry picked from commit 5598a16bdb74d0ab6b5623dbaa1336ed96667a24)
---
 plugins/inputs/mqtt_consumer/README.md | 60 ++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 3 deletions(-)

diff --git a/plugins/inputs/mqtt_consumer/README.md b/plugins/inputs/mqtt_consumer/README.md
index 59ed33854cebc..e0f8984e10071 100644
--- a/plugins/inputs/mqtt_consumer/README.md
+++ b/plugins/inputs/mqtt_consumer/README.md
@@ -87,6 +87,13 @@ and creates metrics using one of the supported [input data formats][].
   #      key = type
 ```
 
+## Example Output
+
+```text
+mqtt_consumer,host=pop-os,topic=telegraf/host01/cpu value=45i 1653579140440951943
+mqtt_consumer,host=pop-os,topic=telegraf/host01/cpu value=100i 1653579153147395661
+```
+
 ## About Topic Parsing
 
 The MQTT topic as a whole is stored as a tag, but this can be far too coarse to
@@ -95,7 +102,7 @@ tag values to be extracted from the MQTT topic letting you store the information
 provided in the topic in a meaningful way. An `_` denotes an ignored entry in
 the topic path. Please see the following example.
 
-## Example Configuration for topic parsing
+### Topic Parsing Example
 
 ```toml
 [[inputs.mqtt_consumer]]
@@ -127,12 +134,59 @@ the topic path. Please see the following example.
       test = "int"
 ```
 
-## Example Output
+Will result in the following metric:
 
-```shell
+```text
 cpu,host=pop-os,tag=telegraf,topic=telegraf/one/cpu/23 value=45,test=23i 1637014942460689291
 ```
 
+## Field Pivoting Example
+
+You can use the pivot processor to rotate single
+valued metrics into a multi field metric.
+For more info check out the pivot processors
+[here][1].
+
+For this example these are the topics:
+
+```text
+/sensors/CLE/v1/device5/temp
+/sensors/CLE/v1/device5/rpm
+/sensors/CLE/v1/device5/ph
+/sensors/CLE/v1/device5/spin
+```
+
+And these are the metrics:
+
+```text
+sensors,site=CLE,version=v1,device_name=device5,field=temp value=390
+sensors,site=CLE,version=v1,device_name=device5,field=rpm value=45.0
+sensors,site=CLE,version=v1,device_name=device5,field=ph value=1.45
+```
+
+Using pivot in the config will rotate the metrics into a multi field metric.
+The config:
+
+```toml
+[[inputs.mqtt_consumer]]
+    ....
+    topics = "/sensors/#"
+    [[inputs.mqtt_consumer.topic_parsing]]
+        measurement = "/measurement/_/_/_/_"
+        tags = "/_/site/version/device_name/field"
+[[processors.pivot]]
+    tag_key = "field"
+    value_key = "value"
+```
+
+Will result in the following metric:
+
+```text
+sensors,site=CLE,version=v1,device_name=device5 temp=390,rpm=45.0,ph=1.45
+```
+
+[1]: <https://github.com/influxdata/telegraf/tree/master/plugins/processors/pivot> "Pivot Processor"
+
 ## Metrics
 
 - All measurements are tagged with the incoming topic, ie