Readme, code changes and test coverage expansion based on review comments

Author: rnishtala-sumo

.chloggen/ottl-replace-pattern.yaml

@@ -7,7 +7,7 @@ change_type: enhancement
 component: pkg/ottl
 
 # A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
-note: Add optional parameters to converters
+note: Add optional Converter parameters to replacement Editors
 
 # Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
 issues: [27235]
@@ -16,7 +16,7 @@ issues: [27235]
 # These lines will be padded with 2 spaces and then inserted directly into the document.
 # Use pipe (|) for multiline entries.
 subtext: |
-  Hashing functions are passed as optional arguments to the following converters:
+  Functions to modify matched text during replacement can now be passed as optional arguments to the following Editors:
   - `replace_pattern`
   - `replace_all_patterns`
   - `replace_match`

pkg/ottl/ottlfuncs/README.md

@@ -57,6 +57,7 @@ The key will be deleted from the map.
 
 Examples:
 
+
 - `delete_key(attributes, "http.request.header.authorization")`
 
 - `delete_key(resource.attributes, "http.request.header.authorization")`
@@ -73,6 +74,7 @@ All keys that match the pattern will be deleted from the map.
 
 Examples:
 
+
 - `delete_key(attributes, "http.request.header.authorization")`
 
 - `delete_key(resource.attributes, "http.request.header.authorization")`
@@ -91,6 +93,7 @@ Examples:
 
 - `keep_keys(attributes, ["http.method"])`
 
+
 - `keep_keys(resource.attributes, ["http.method", "http.route", "http.url"])`
 
 ### limit
@@ -113,6 +116,7 @@ Examples:
 
 - `limit(attributes, 100, [])`
 
+
 - `limit(resource.attributes, 50, ["http.host", "http.method"])`
 
 ### merge_maps
@@ -135,18 +139,19 @@ Examples:
 
 - `merge_maps(attributes, ParseJSON(body), "upsert")`
 
+
 - `merge_maps(attributes, ParseJSON(attributes["kubernetes"]), "update")`
 
+
 - `merge_maps(attributes, resource.attributes, "insert")`
 
 ### replace_all_matches
 
-`replace_all_matches(target, pattern, replacement, hashFunction)`
+`replace_all_matches(target, pattern, replacement, function)`
 
 The `replace_all_matches` function replaces any matching string value with the replacement string.
 
-`target` is a path expression to a `pdata.Map` type field. `pattern` is a string following [filepath.Match syntax](https://pkg.go.dev/path/filepath#Match). `replacement` is either a path expression to a string telemetry field or a literal string. `hashFunction` is an optional argument
-that creates a hash of `replacement` and then replaces any matching string with the hash value.
+`target` is a path expression to a `pdata.Map` type field. `pattern` is a string following [filepath.Match syntax](https://pkg.go.dev/path/filepath#Match). `replacement` is either a path expression to a string telemetry field or a literal string. `function` is an optional argument that can take in any Converter that accepts a (`replacement`) string and returns a string. An example is a hash function that replaces any matching string with the hash value of `replacement`.
 
 Each string value in `target` that matches `pattern` will get replaced with `replacement`. Non-string values are ignored.
 
@@ -160,7 +165,7 @@ Examples:
 
 ### replace_all_patterns
 
-`replace_all_patterns(target, mode, regex, replacement, hashFunction)`
+`replace_all_patterns(target, mode, regex, replacement, function)`
 
 The `replace_all_patterns` function replaces any segments in a string value or key that match the regex pattern with the replacement string.
 
@@ -172,7 +177,7 @@ If one or more sections of `target` match `regex` they will get replaced with `r
 
 The `replacement` string can refer to matched groups using [regexp.Expand syntax](https://pkg.go.dev/regexp#Regexp.Expand).
 
-The `hashFunction` is an optional argument that creates a hash of `replacement` and then replaces the regex pattern with the hash value.
+The `function` is an optional argument that can take in any Converter that accepts a (`replacement`) string and returns a string. An example is a hash function that replaces any matching regex pattern with the hash value of `replacement`.
 
 There is currently a bug with OTTL that does not allow the pattern to end with `\\"`.
 If your pattern needs to end with backslashes, add something inconsequential to the end of the pattern such as `{1}`, `$`, or `.*`.
@@ -191,15 +196,15 @@ If using OTTL outside of collector configuration, `$` should not be escaped and
 
 ### replace_match
 
-`replace_match(target, pattern, replacement, hashFunction)`
+`replace_match(target, pattern, replacement, function)`
 
 The `replace_match` function allows replacing entire strings if they match a glob pattern.
 
 `target` is a path expression to a telemetry field. `pattern` is a string following [filepath.Match syntax](https://pkg.go.dev/path/filepath#Match). `replacement` is either a path expression to a string telemetry field or a literal string.
 
 If `target` matches `pattern` it will get replaced with `replacement`.
 
-The `hashFunction` is an optional argument that creates a hash of `replacement` and then replaces entire strings if they match a glob pattern with the hash value.
+The `function` is an optional argument that can take in any Converter that accepts a (`replacement`) string and returns a string. An example is a hash function that replaces any matching glob pattern with the hash value of `replacement`.
 
 There is currently a bug with OTTL that does not allow the pattern to end with `\\"`.
 [See Issue 23238 for details](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/23238).
@@ -211,7 +216,7 @@ Examples:
 
 ### replace_pattern
 
-`replace_pattern(target, regex, replacement, hashFunction)`
+`replace_pattern(target, regex, replacement, function)`
 
 The `replace_pattern` function allows replacing all string sections that match a regex pattern with a new value.
 
@@ -221,7 +226,7 @@ If one or more sections of `target` match `regex` they will get replaced with `r
 
 The `replacement` string can refer to matched groups using [regexp.Expand syntax](https://pkg.go.dev/regexp#Regexp.Expand).
 
-The `hashFunction` is an optional argument that creates a hash of `replacement` and then replaces all string sections that match a regex pattern with the hash value.
+The `function` is an optional argument that can take in any Converter that accepts a (`replacement`) string and returns a string. An example is a hash function that replaces a matching regex pattern with the hash value of `replacement`.
 
 There is currently a bug with OTTL that does not allow the pattern to end with `\\"`.
 If your pattern needs to end with backslashes, add something inconsequential to the end of the pattern such as `{1}`, `$`, or `.*`.
@@ -251,10 +256,13 @@ Examples:
 
 - `set(attributes["http.path"], "/foo")`
 
+
 - `set(name, attributes["http.route"])`
 
+
 - `set(trace_state["svc"], "example")`
 
+
 - `set(attributes["source"], trace_state["source"])`
 
 ### truncate_all
@@ -271,6 +279,7 @@ Examples:
 
 - `truncate_all(attributes, 100)`
 
+
 - `truncate_all(resource.attributes, 50)`
 
 ## Converters
@@ -327,8 +336,10 @@ Examples:
 
 - `Concat([attributes["http.method"], attributes["http.path"]], ": ")`
 
+
 - `Concat([name, 1], " ")`
 
+
 - `Concat(["HTTP method is: ", attributes["http.method"]], "")`
 
 ### ConvertCase
@@ -402,6 +413,7 @@ Examples:
 
 - `FNV(attributes["device.name"])`
 
+
 - `FNV("name")`
 
 ### Hours
@@ -441,6 +453,7 @@ Examples:
 
 - `Int(attributes["http.status_code"])`
 
+
 - `Int("2.0")`
 
 ### IsMap
@@ -457,6 +470,7 @@ Examples:
 
 - `IsMap(body)`
 
+
 - `IsMap(attributes["maybe a map"])`
 
 ### IsMatch
@@ -485,6 +499,7 @@ Examples:
 
 - `IsMatch(attributes["http.path"], "foo")`
 
+
 - `IsMatch("string", ".*ring")`
 
 ### IsString
@@ -540,6 +555,7 @@ Examples:
 
 - `Log(attributes["duration_ms"])`
 
+
 - `Int(Log(attributes["duration_ms"])`
 
 ### Microseconds
@@ -636,8 +652,10 @@ Examples:
 
 - `ParseJSON("{\"attr\":true}")`
 
+
 - `ParseJSON(attributes["kubernetes"])`
 
+
 - `ParseJSON(body)`
 
 ### Seconds
@@ -670,6 +688,7 @@ Examples:
 
 - `SHA1(attributes["device.name"])`
 
+
 - `SHA1("name")`
 
 **Note:** According to the National Institute of Standards and Technology (NIST), SHA1 is no longer a recommended hash function. It should be avoided except when required for compatibility. New uses should prefer FNV whenever possible.
@@ -690,6 +709,7 @@ Examples:
 
 - `SHA256(attributes["device.name"])`
 
+
 - `SHA256("name")`
 
 **Note:** According to the National Institute of Standards and Technology (NIST), SHA256 is no longer a recommended hash function. It should be avoided except when required for compatibility. New uses should prefer FNV whenever possible.
@@ -708,7 +728,7 @@ Examples:
 
 ### Split
 
-`Split(target, delimiter)`
+```Split(target, delimiter)```
 
 The `Split` Converter separates a string by the delimiter, and returns an array of substrings.
 

pkg/ottl/ottlfuncs/func_replace_all_matches.go

@@ -20,6 +20,10 @@ type ReplaceAllMatchesArguments[K any] struct {
 	Function    ottl.Optional[ottl.FunctionGetter[K]]
 }
 
+type replaceAllMatchesFuncArgs[K any] struct {
+	Input ottl.StringGetter[K]
+}
+
 func NewReplaceAllMatchesFactory[K any]() ottl.Factory[K] {
 	return ottl.NewFactory("replace_all_matches", &ReplaceAllMatchesArguments[K]{}, createReplaceAllMatchesFunction[K])
 }
@@ -36,12 +40,12 @@ func createReplaceAllMatchesFunction[K any](_ ottl.FunctionContext, oArgs ottl.A
 
 func replaceAllMatches[K any](target ottl.PMapGetter[K], pattern string, replacement ottl.StringGetter[K], fn ottl.Optional[ottl.FunctionGetter[K]]) (ottl.ExprFunc[K], error) {
 	glob, err := glob.Compile(pattern)
-	var replacementVal string
 	if err != nil {
 		return nil, fmt.Errorf("the pattern supplied to replace_match is not a valid pattern: %w", err)
 	}
 	return func(ctx context.Context, tCtx K) (interface{}, error) {
 		val, err := target.Get(ctx, tCtx)
+		var replacementVal string
 		if err != nil {
 			return nil, err
 		}
@@ -52,15 +56,19 @@ func replaceAllMatches[K any](target ottl.PMapGetter[K], pattern string, replace
 			}
 		} else {
 			fnVal := fn.Get()
-			replacementExpr, errNew := fnVal.Get(&FuncArgs[K]{Input: replacement})
+			replacementExpr, errNew := fnVal.Get(&replaceAllMatchesFuncArgs[K]{Input: replacement})
 			if errNew != nil {
 				return nil, errNew
 			}
 			replacementValRaw, errNew := replacementExpr.Eval(ctx, tCtx)
 			if errNew != nil {
 				return nil, errNew
 			}
-			replacementVal = replacementValRaw.(string)
+			replacementValStr, ok := replacementValRaw.(string)
+			if !ok {
+				return nil, fmt.Errorf("replacement value is not a string")
+			}
+			replacementVal = replacementValStr
 		}
 		val.Range(func(key string, value pcommon.Value) bool {
 			if glob.Match(value.Str()) {

pkg/ottl/ottlfuncs/func_replace_all_matches_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/collector/component/componenttest"
 	"go.opentelemetry.io/collector/pdata/pcommon"
 
@@ -131,6 +132,57 @@ func Test_replaceAllMatches_bad_input(t *testing.T) {
 	assert.Error(t, err)
 }
 
+func Test_replaceAllMatches_bad_function_input(t *testing.T) {
+	input := pcommon.NewValueInt(1)
+	target := &ottl.StandardPMapGetter[interface{}]{
+		Getter: func(ctx context.Context, tCtx interface{}) (interface{}, error) {
+			return tCtx, nil
+		},
+	}
+	replacement := &ottl.StandardStringGetter[interface{}]{
+		Getter: func(context.Context, interface{}) (interface{}, error) {
+			return nil, nil
+		},
+	}
+	function := ottl.Optional[ottl.FunctionGetter[interface{}]]{}
+
+	exprFunc, err := replaceAllMatches[interface{}](target, "regexp", replacement, function)
+	assert.NoError(t, err)
+
+	result, err := exprFunc(nil, input)
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "expected pcommon.Map")
+	assert.Nil(t, result)
+}
+
+func Test_replaceAllMatches_bad_function_result(t *testing.T) {
+	input := pcommon.NewValueInt(1)
+	target := &ottl.StandardPMapGetter[interface{}]{
+		Getter: func(ctx context.Context, tCtx interface{}) (interface{}, error) {
+			return tCtx, nil
+		},
+	}
+	replacement := &ottl.StandardStringGetter[interface{}]{
+		Getter: func(context.Context, interface{}) (interface{}, error) {
+			return "{replacement}", nil
+		},
+	}
+	ottlValue := ottl.StandardFunctionGetter[interface{}]{
+		FCtx: ottl.FunctionContext{
+			Set: componenttest.NewNopTelemetrySettings(),
+		},
+		Fact: StandardConverters[interface{}]()["IsString"],
+	}
+	function := ottl.NewTestingOptional[ottl.FunctionGetter[interface{}]](ottlValue)
+
+	exprFunc, err := replaceAllMatches[interface{}](target, "regexp", replacement, function)
+	assert.NoError(t, err)
+
+	result, err := exprFunc(nil, input)
+	require.Error(t, err)
+	assert.Nil(t, result)
+}
+
 func Test_replaceAllMatches_get_nil(t *testing.T) {
 	target := &ottl.StandardPMapGetter[interface{}]{
 		Getter: func(ctx context.Context, tCtx interface{}) (interface{}, error) {

pkg/ottl/ottlfuncs/func_replace_all_patterns.go

@@ -26,6 +26,10 @@ type ReplaceAllPatternsArguments[K any] struct {
 	Function     ottl.Optional[ottl.FunctionGetter[K]]
 }
 
+type replaceAllPatternFuncArgs[K any] struct {
+	Input ottl.StringGetter[K]
+}
+
 func NewReplaceAllPatternsFactory[K any]() ottl.Factory[K] {
 	return ottl.NewFactory("replace_all_patterns", &ReplaceAllPatternsArguments[K]{}, createReplaceAllPatternsFunction[K])
 }
@@ -42,7 +46,6 @@ func createReplaceAllPatternsFunction[K any](_ ottl.FunctionContext, oArgs ottl.
 
 func replaceAllPatterns[K any](target ottl.PMapGetter[K], mode string, regexPattern string, replacement ottl.StringGetter[K], fn ottl.Optional[ottl.FunctionGetter[K]]) (ottl.ExprFunc[K], error) {
 	compiledPattern, err := regexp.Compile(regexPattern)
-	var replacementVal string
 	if err != nil {
 		return nil, fmt.Errorf("the regex pattern supplied to replace_all_patterns is not a valid pattern: %w", err)
 	}
@@ -52,6 +55,7 @@ func replaceAllPatterns[K any](target ottl.PMapGetter[K], mode string, regexPatt
 
 	return func(ctx context.Context, tCtx K) (interface{}, error) {
 		val, err := target.Get(ctx, tCtx)
+		var replacementVal string
 		if err != nil {
 			return nil, err
 		}
@@ -62,15 +66,19 @@ func replaceAllPatterns[K any](target ottl.PMapGetter[K], mode string, regexPatt
 			}
 		} else {
 			fnVal := fn.Get()
-			replacementExpr, errNew := fnVal.Get(&FuncArgs[K]{Input: replacement})
+			replacementExpr, errNew := fnVal.Get(&replaceAllPatternFuncArgs[K]{Input: replacement})
 			if errNew != nil {
 				return nil, errNew
 			}
 			replacementValRaw, errNew := replacementExpr.Eval(ctx, tCtx)
 			if errNew != nil {
 				return nil, errNew
 			}
-			replacementVal = replacementValRaw.(string)
+			replacementValStr, ok := replacementValRaw.(string)
+			if !ok {
+				return nil, fmt.Errorf("replacement value is not a string")
+			}
+			replacementVal = replacementValStr
 		}
 		updated := pcommon.NewMap()
 		updated.EnsureCapacity(val.Len())