processor_labels: Add a documentation for processor_labels

Signed-off-by: Hiroshi Hatake <hiroshi@chronosphere.io>

SUMMARY.md

@@ -129,6 +129,7 @@
   * [Logfmt](pipeline/parsers/logfmt.md)
   * [Decoders](pipeline/parsers/decoders.md)
 * [Processors](pipeline/processors/README.md)
+  * [Labels](pipeline/processors/labels.md)
   * [Content Modifier](pipeline/processors/content-modifier.md)
   * [Metrics Selector](pipeline/processors/metrics-selector.md)
   * [SQL](pipeline/processors/sql.md)

installation/sources/build-and-install.md

@@ -220,3 +220,4 @@ The following table describes the processors available on this version:
 | option | description | default |
 | :--- | :--- | :--- |
 | [FLB\_PROCESSOR\_METRICS\_SELECTOR](../../pipeline/processors/metrics-selector.md) | Enable metrics selector processor | On |
+| [FLB\_PROCESSOR\_LABELS](../../pipeline/processors/labels.md) | Enable metrics label manipulation processor | On |

pipeline/processors/labels.md

@@ -0,0 +1,88 @@
+# Labels
+
+The **labels** processor allows you to manipulate the labels of Metrics.
+
+Similar to the functionality exposed by filters, this processor presents a enriching/modifying mechanism to perform such operations for labels manipulation.
+The most significant difference is that processors perform better than filters, and when chaining them, there are no encoding/decoding performance penalties.
+
+Note that processors and this specific component can only be enabled using the new YAML configuration format. Classic mode configuration format doesn't support processors.
+
+## Configuration Parameters
+
+| Key         | Description |
+| :---------- | :--- |
+| update  | Update an existing key with a value into metrics. The key-value pair is required. |
+| insert  | Insert a new key with a value into metrics. The key-value pair is required. |
+| upsert  | Upsert a specific key with a value, the `upsert` operation will try to update the value of the key. If the key does not exist, the key will be created. The key-value pair is required. |
+| delete  | Delete a key from the labels of metrics. The key-value pair is required. |
+| hash    | Replace the key value with a hash generated by the SHA-1 algorithm from the specified label name, the binary value generated is finally set as an hex string representation. |
+
+
+#### Update example
+
+Change the name of `key2` to `test`:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            update: name fluentbit
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+#### Insert example
+
+The following example appends the key `color` with the value `blue` to the log stream.
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            insert: agent fluentbit
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+#### Upsert example
+
+Update the value of `key1` and insert `key2`:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            upsert: name fluentbit
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+
+#### Hash example
+
+Apply the SHA-256 algorithm for the value of the key `password`:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            hash: hostname
+  outputs:
+    - name : stdout
+      match: '*'
+```