[pkg/stanza] Add 'regex_replace' operator

.chloggen/regex-replace.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: 'enhancement'
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: pkg/stanza
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add 'regex_replace' operator
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [37443]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

pkg/stanza/adapter/register.go

@@ -26,6 +26,7 @@ import (
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/move"
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/noop"
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/recombine"
+	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/regexreplace"
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/remove"
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/retain"
 	_ "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/router"

pkg/stanza/docs/operators/README.md

@@ -41,6 +41,7 @@ General purpose:
 - [move](./move.md)
 - [noop](./noop.md)
 - [recombine](./recombine.md)
+- [regex_replace](./regex_replace.md)
 - [remove](./remove.md)
 - [retain](./retain.md)
 - [router](./router.md)

pkg/stanza/docs/operators/regex_replace.md

@@ -0,0 +1,142 @@
+## `regex_replace` operator
+
+The `regex_replace` operator parses the string-typed field selected by `field` with the given user-defined or well-known regular expression.
+Optionally, it replaces the matched string.
+
+#### Regex Syntax
+
+This operator makes use of [Go regular expression](https://github.com/google/re2/wiki/Syntax). When writing a regex, consider using a tool such as [regex101](https://regex101.com/?flavor=golang).
+
+### Configuration Fields
+
+| Field          | Default                          | Description |
+| ---            | ---                              | ---         |
+| `id`           | `regex_replace`                  | A unique identifier for the operator. |
+| `output`       | Next in pipeline                 | The connected operator(s) that will receive all outbound entries. |
+| `field`        | required                         | The [field](../types/field.md) to strip. Must be a string. |
+| `regex`        | `regex` or `regex_name` required | A [Go regular expression](https://github.com/google/re2/wiki/Syntax). |
+| `regex_name`   | `regex` or `regex_name` required | A well-known regex to use. See below for a list of possible values. |
+| `replace_with` | optional                         | The [field](../types/field.md) to strip. Must be a string. |
+| `on_error`     | `send`                           | The behavior of the operator if it encounters an error. See [on_error](../types/on_error.md). |
+| `if`           |                                  | An [expression](../types/expression.md) that, when set, will be evaluated to determine whether this operator should be used for the given entry. This allows you to do easy conditional parsing without branching logic with routers. |
+
+#### Well-known regular expressions
+
+| Name                     | Description |
+| ---                      | ---         |
+| `ansi_control_sequences` | ANSI "Control Sequence Introducer (CSI)" escape codes starting with `ESC [` |
+
+### Example Configurations
+
+#### Collapse spaces 
+
+Configuration:
+```yaml
+- type: regex_replace
+  regex: " +"
+  replace_with: " "
+  field: body
+```
+
+<table>
+<tr><td> Input Entry </td> <td> Output Entry </td></tr>
+<tr>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "Hello  World"
+}
+```
+
+</td>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "Hello World"
+}
+```
+
+</td>
+</tr>
+</table>
+
+#### Match and replace with groups
+
+Configuration:
+```yaml
+- type: regex_replace
+  regex: "{(.*)}"
+  replace_with: "${1}"
+  field: body
+```
+
+<table>
+<tr><td> Input Entry </td> <td> Output Entry </td></tr>
+<tr>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "{a}{bb}{ccc}"
+}
+```
+
+</td>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "abbccc"
+}
+```
+
+</td>
+</tr>
+</table>
+
+#### Remove all ANSI color escape codes from the body
+
+Configuration:
+```yaml
+- type: regex_replace
+  regex_name: ansi_control_sequences
+  field: body
+```
+
+<table>
+<tr><td> Input Entry </td> <td> Output Entry </td></tr>
+<tr>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "\x1b[31mred\x1b[0m"
+}
+```
+
+</td>
+<td>
+
+```json
+{
+  "resource": { },
+  "attributes": { },
+  "body": "red"
+}
+```
+
+</td>
+</tr>
+</table>

pkg/stanza/operator/transformer/regexreplace/config.go

@@ -0,0 +1,80 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package regexreplace // import "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/transformer/regexreplace"
+
+import (
+	"fmt"
+	"regexp"
+
+	"go.opentelemetry.io/collector/component"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/entry"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/stanza/operator/helper"
+)
+
+const operatorType = "regex_replace"
+
+// derived from https://en.wikipedia.org/wiki/ANSI_escape_code#CSIsection
+var ansiCsiEscapeRegex = regexp.MustCompile(`\x1B\[[\x30-\x3F]*[\x20-\x2F]*[\x40-\x7E]`)
+
+func init() {
+	operator.Register(operatorType, func() operator.Builder { return NewConfig() })
+}
+
+// NewConfig creates a new ansi_control_sequences config with default values
+func NewConfig() *Config {
+	return NewConfigWithID(operatorType)
+}
+
+// NewConfigWithID creates a new ansi_control_sequences config with default values
+func NewConfigWithID(operatorID string) *Config {
+	return &Config{
+		TransformerConfig: helper.NewTransformerConfig(operatorID, operatorType),
+	}
+}
+
+// Config is the configuration of an ansi_control_sequences operator.
+type Config struct {
+	helper.TransformerConfig `mapstructure:",squash"`
+	RegexName                string      `mapstructure:"regex_name"`
+	Regex                    string      `mapstructure:"regex"`
+	ReplaceWith              string      `mapstructure:"replace_with"`
+	Field                    entry.Field `mapstructure:"field"`
+}
+
+func (c *Config) getRegexp() (*regexp.Regexp, error) {
+	if (c.RegexName == "") == (c.Regex == "") {
+		return nil, fmt.Errorf("either regex or regex_name must be set")
+	}
+
+	switch c.RegexName {
+	case "ansi_control_sequences":
+		return ansiCsiEscapeRegex, nil
+	case "":
+		return regexp.Compile(c.Regex)
+	default:
+		return nil, fmt.Errorf("regex_name %s is unknown", c.RegexName)
+	}
+}
+
+// Build will build an ansi_control_sequences operator.
+func (c Config) Build(set component.TelemetrySettings) (operator.Operator, error) {
+	transformerOperator, err := c.TransformerConfig.Build(set)
+	if err != nil {
+		return nil, err
+	}
+
+	regexp, err := c.getRegexp()
+	if err != nil {
+		return nil, err
+	}
+
+	return &Transformer{
+		TransformerOperator: transformerOperator,
+		field:               c.Field,
+		regexp:              regexp,
+		replaceWith:         c.ReplaceWith,
+	}, nil
+}