Merge pull request #1621 from fluent/alexakreizinger/sc-128556/customer-complained-about-misleading-documentation

Author: alexakreizinger

pipeline/processors/metrics-selector.md

@@ -1,27 +1,45 @@
 # Metrics Selector
 
-The **metric_selector** processor allows you to select metrics to include or exclude (similar to the `grep` filter for logs).
+The _Metrics Selector_ processor lets you choose which metrics to include or exclude, similar to the [Grep](../pipeline/filters/grep) filter for logs.
 
 <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=326269f3-cfea-472d-9169-1de32c142b90" />
 
-## Configuration Parameters <a id="config"></a>
+## Configuration parameters
 
-The native processor plugin supports the following configuration parameters:
+The Metrics Selector processor supports the following configuration parameters:
 
 | Key         | Description | Default |
 | :---------- | :--- | :--- |
-| Metric\_Name | Keep metrics in which the metric of name matches with the actual name or the regular expression. | |
-| Context | Specify matching context. Currently, metric\_name and delete\_label\_value are only supported. | `Metrics_Name` |
-| Action | Specify the action for specified metrics. INCLUDE and EXCLUDE are allowed. | |
-| Operation\_Type | Specify the operation type of action for metrics payloads. PREFIX and SUBSTRING are allowed. | |
-| Label | Specify a label key and value pair. | |
+| `metric_name` | The string that determines which metrics are affected by this processor, depending on the active [matching operation](#matching-operations). | |
+| `context` | Specifies matching context. Possible values: `metric_name` or `delete_label`. | `metrics_name` |
+| `action` | Specifies whether to include or exclude matching metrics. Possible values: `INCLUDE` or `EXCLUDE`. | |
+| `operation_type` | Specifies the [matching operation](#matching-operations) to apply to the value of `metric_name`. Possible values: `PREFIX` or `SUBSTRING`. | |
+| `label` | Specifies a label key and value pair. | |
 
-## Configuration Examples <a id="config_example"></a>
+## Matching operations
 
-Here is a basic configuration example.
+The Metrics Selector processor has two matching operations: prefix matching and substring matching.
+
+### Prefix matching
+
+Prefix matching compares the value of `metric_name` to the beginning of each incoming metric name. For example, `metric_name: fluentbit_input` results in a match for metrics named `fluentbit_input_records`, but not for metrics named `total_fluentbit_input`.
+
+If no `operation_type` value is specified and the value of `metric_name` is a standard string, the Metrics Selector processor defaults to prefix matching.
+
+### Substring matching
+
+Substring matching treats the value of `metric_name` as a regex pattern, and compares this pattern against each incoming metric name accordingly. This pattern can appear anywhere within the name of the incoming metric. For example, `metric_name: bytes` results in a match for metrics named `bytes_total` and metrics named `input_bytes_count`.
+
+If the value of `metric_name` is a string wrapped in forward slashes (for example, `metric_name: /storage..*/`), the Metrics Selector processor defaults to substring matching, regardless of whether an `operation_type` value is specified. This means that a `metric_name` value wrapped in forward slashes will always use substring matching, even if `operation_type` is set to `PREFIX`.
+
+However, if `operation_type` is explicitly set to `SUBSTRING`, you don't need to wrap the value of `metric_name` in forward slashes.
+
+## Configuration examples
+
+The following examples show possible configurations of the Metrics Selector processor.
+
+### Without `context`
 
-{% tabs %}
-{% tab title="fluent-bit.yaml" %}
 ```yaml
 service:
   flush: 5
@@ -51,9 +69,9 @@ pipeline:
     - name: stdout
       match: '*'
 ```
-{% endtab %}
 
-{% tab title="context-delete\_label\_value.yaml" %}
+### With `context`
+
 ```yaml
 service:
   flush: 5
@@ -80,14 +98,3 @@ pipeline:
     - name: stdout
       match: '*'
 ```
-{% endtab %}
-{% endtabs %}
-
-
-All processors are only valid with the YAML configuration format. 
-Processor configuration should be located under the relevant input or output plugin configuration.
-
-Metric\_Name parameter will translate the strings which is quoted with backslashes `/.../` as Regular expressions.
-Without them, users need to specify Operation\_Type whether prefix matching or substring matching.
-The default operation is prefix matching.
-For example, `/chunks/` will be translated as a regular expression.