processor_labels: Add a documentation for processor_labels (#1371)

* processor_labels: Add a documentation for processor_labels Signed-off-by: Hiroshi Hatake <[email protected]> * processor_labels: Use SHA-256 instead of SHA-1 This is because using hash algorithm is actually SHA-256. Signed-off-by: Hiroshi Hatake <[email protected]> * Update labels.md Signed-off-by: Hiroshi Hatake <[email protected]> Co-authored-by: Pat <[email protected]> * processor_labels: Clarify an effect of absence of the target key when insert and delete operations Signed-off-by: Hiroshi Hatake <[email protected]> * Update pipeline/processors/labels.md Co-authored-by: Craig Norris <[email protected]> Signed-off-by: Hiroshi Hatake <[email protected]> * Update pipeline/processors/labels.md Co-authored-by: Craig Norris <[email protected]> Signed-off-by: Hiroshi Hatake <[email protected]> * Update pipeline/processors/labels.md Co-authored-by: Craig Norris <[email protected]> Signed-off-by: Hiroshi Hatake <[email protected]> * Update pipeline/processors/labels.md Co-authored-by: Craig Norris <[email protected]> Signed-off-by: Hiroshi Hatake <[email protected]> * Update pipeline/processors/labels.md Co-authored-by: Craig Norris <[email protected]> Signed-off-by: Hiroshi Hatake <[email protected]> --------- Signed-off-by: Hiroshi Hatake <[email protected]> Co-authored-by: Pat <[email protected]> Co-authored-by: Craig Norris <[email protected]>
fluent · Jul 26, 2024 · ec2542a · ec2542a
1 parent ac4e7c1
commit ec2542a
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 0 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -130,6 +130,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)

diff --git a/installation/sources/build-and-install.md b/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 |
diff --git a/pipeline/processors/labels.md b/pipeline/processors/labels.md
@@ -0,0 +1,110 @@
+# Labels
+
+The **labels** processor lets you manipulate the labels of metrics.
+
+Similar to filters, this processor presents a enriching/modifying mechanism to
+perform operations for labels manipulation. The most significant difference is
+that processors perform better than filters, and when chaining them there are no
+encoding or decoding performance penalties.
+
+{% hint style="info" %}
+**Note:** Both processors and this specific component can be enabled only by using
+the YAML configuration format. Classic mode configuration format doesn't support
+processors.
+{% endhint %}
+
+## Configuration Parameters
+
+| Key    | Description |
+| :----- | :---------- |
+| update | Update an existing key with a value into metrics. The key/value pair is required. If the specified key doesn't exist, the operation silently fails and has no effect. |
+| 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. If the specified key doesn't exist, the operation silently fails and has no effect. |
+| hash   | Replace the key value with a hash generated by the SHA-256 algorithm from the specified label name. The generated binary value is set as a hex string. |
+
+#### Update example
+
+Change the value of the `name` to `fluentbit`:
+
+```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 `agent` with the value `fluentbit` as the label
+of metrics:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            insert: agent fluentbit
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+#### Upsert example
+
+Upsert the value of `name` and insert `fluentbit`:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            upsert: name fluentbit
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+#### Delete example
+
+Delete containing `name` key from metrics:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            delete: name
+  outputs:
+    - name : stdout
+      match: '*'
+```
+
+#### Hash example
+
+Apply the SHA-1 algorithm for the value of the key `hostname`:
+
+```yaml
+pipeline:
+  inputs:
+    - name: fluentbit_metrics
+      processors:
+        metrics:
+          - name: labels
+            hash: hostname
+  outputs:
+    - name : stdout
+      match: '*'
+```