[pkg/ottl] Add parser collection option to allow configuring extra context inferrer conditions (#39465)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

Added a new option `ottl.WithContextInferenceConditions` to the
`ParserCollection.ParseStataments` so API users can provide extra
context inferrer's conditions and have theirs hints considered by the
default context inferrer.

Follow up:
#39463
(includes this PR changes)

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Relates to
#39455

<!--Describe what testing was performed and which tests were added.-->
#### Testing
Unit tests

Author: edmocosta

.chloggen/add-parser-collection-ctx-inference-conditions-opts.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/ottl
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add `ottl.WithContextInferenceConditions` option to allow configuring extra context inferrer OTTL conditions"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [39455]
+
+# (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: [api]

pkg/ottl/context_inferrer.go

@@ -32,6 +32,8 @@ type contextInferrer interface {
 	inferFromStatements(statements []string) (string, error)
 	// inferFromConditions returns the OTTL context inferred from the given conditions.
 	inferFromConditions(conditions []string) (string, error)
+	// infer returns the OTTL context inferred from the given statements and conditions.
+	infer(statements []string, conditions []string) (string, error)
 }
 
 type priorityContextInferrer struct {
@@ -85,23 +87,37 @@ func withContextInferrerPriorities(priorities []string) priorityContextInferrerO
 }
 
 func (s *priorityContextInferrer) inferFromConditions(conditions []string) (inferredContext string, err error) {
-	return s.infer(conditions, s.getConditionHints)
+	return s.infer(nil, conditions)
 }
 
 func (s *priorityContextInferrer) inferFromStatements(statements []string) (inferredContext string, err error) {
-	return s.infer(statements, s.getStatementHints)
+	return s.infer(statements, nil)
 }
 
-// hinterFunc is used by the infer function to generate the hints (paths, functions, enums, etc.) for the given OTTL.
-type hinterFunc func(string) ([]path, map[string]struct{}, map[enumSymbol]struct{}, error)
-
-func (s *priorityContextInferrer) infer(ottls []string, hinter hinterFunc) (inferredContext string, err error) {
-	s.telemetrySettings.Logger.Debug("Inferring context from OTTL",
+func (s *priorityContextInferrer) infer(statements []string, conditions []string) (inferredContext string, err error) {
+	var statementsHints, conditionsHints []priorityContextInferrerHints
+	if len(statements) > 0 {
+		statementsHints, err = s.getStatementsHints(statements)
+		if err != nil {
+			return "", err
+		}
+	}
+	if len(conditions) > 0 {
+		conditionsHints, err = s.getConditionsHints(conditions)
+		if err != nil {
+			return "", err
+		}
+	}
+	s.telemetrySettings.Logger.Debug("Inferring context from statements and conditions",
 		zap.Strings("candidates", maps.Keys(s.contextCandidate)),
 		zap.Any("priority", s.contextPriority),
-		zap.Strings("values", ottls),
+		zap.Strings("statements", statements),
+		zap.Strings("conditions", conditions),
 	)
+	return s.inferFromHints(append(statementsHints, conditionsHints...))
+}
 
+func (s *priorityContextInferrer) inferFromHints(hints []priorityContextInferrerHints) (inferredContext string, err error) {
 	defer func() {
 		if inferredContext != "" {
 			s.telemetrySettings.Logger.Debug(fmt.Sprintf(`Inferred context: "%s"`, inferredContext))
@@ -114,12 +130,8 @@ func (s *priorityContextInferrer) infer(ottls []string, hinter hinterFunc) (infe
 	requiredEnums := map[enumSymbol]struct{}{}
 
 	var inferredContextPriority int
-	for _, ottl := range ottls {
-		ottlPaths, ottlFunctions, ottlEnums, hinterErr := hinter(ottl)
-		if hinterErr != nil {
-			return "", hinterErr
-		}
-		for _, p := range ottlPaths {
+	for _, hint := range hints {
+		for _, p := range hint.paths {
 			candidate := p.Context
 			candidatePriority, ok := s.contextPriority[candidate]
 			if !ok {
@@ -130,10 +142,10 @@ func (s *priorityContextInferrer) infer(ottls []string, hinter hinterFunc) (infe
 				inferredContextPriority = candidatePriority
 			}
 		}
-		for function := range ottlFunctions {
+		for function := range hint.functions {
 			requiredFunctions[function] = struct{}{}
 		}
-		for enum := range ottlEnums {
+		for enum := range hint.enumsSymbols {
 			requiredEnums[enum] = struct{}{}
 		}
 	}
@@ -231,68 +243,76 @@ func (s *priorityContextInferrer) sortContextCandidates(candidates []string) {
 	})
 }
 
-// getConditionHints extracts all path, function names (editor and converter), and enumSymbol
+// getConditionsHints extracts all path, function names (editor and converter), and enumSymbol
 // from the given condition. These values are used by the context inferrer as hints to
 // select a context in which the function/enum are supported.
-func (s *priorityContextInferrer) getConditionHints(condition string) ([]path, map[string]struct{}, map[enumSymbol]struct{}, error) {
-	parsed, err := parseCondition(condition)
-	if err != nil {
-		return nil, nil, nil, err
-	}
+func (s *priorityContextInferrer) getConditionsHints(conditions []string) ([]priorityContextInferrerHints, error) {
+	hints := make([]priorityContextInferrerHints, 0, len(conditions))
+	for _, condition := range conditions {
+		parsed, err := parseCondition(condition)
+		if err != nil {
+			return nil, err
+		}
 
-	visitor := newGrammarContextInferrerVisitor()
-	parsed.accept(&visitor)
-	return visitor.paths, visitor.functions, visitor.enumsSymbols, nil
+		visitor := newGrammarContextInferrerVisitor()
+		parsed.accept(&visitor)
+		hints = append(hints, visitor)
+	}
+	return hints, nil
 }
 
-// getStatementHints extracts all path, function names (editor and converter), and enumSymbol
+// getStatementsHints extracts all path, function names (editor and converter), and enumSymbol
 // from the given statement. These values are used by the context inferrer as hints to
 // select a context in which the function/enum are supported.
-func (s *priorityContextInferrer) getStatementHints(statement string) ([]path, map[string]struct{}, map[enumSymbol]struct{}, error) {
-	parsed, err := parseStatement(statement)
-	if err != nil {
-		return nil, nil, nil, err
-	}
-	visitor := newGrammarContextInferrerVisitor()
-	parsed.Editor.accept(&visitor)
-	if parsed.WhereClause != nil {
-		parsed.WhereClause.accept(&visitor)
+func (s *priorityContextInferrer) getStatementsHints(statements []string) ([]priorityContextInferrerHints, error) {
+	hints := make([]priorityContextInferrerHints, 0, len(statements))
+	for _, statement := range statements {
+		parsed, err := parseStatement(statement)
+		if err != nil {
+			return nil, err
+		}
+		visitor := newGrammarContextInferrerVisitor()
+		parsed.Editor.accept(&visitor)
+		if parsed.WhereClause != nil {
+			parsed.WhereClause.accept(&visitor)
+		}
+		hints = append(hints, visitor)
 	}
-	return visitor.paths, visitor.functions, visitor.enumsSymbols, nil
+	return hints, nil
 }
 
-// priorityContextInferrerHintsVisitor is a grammarVisitor implementation that collects
+// priorityContextInferrerHints is a grammarVisitor implementation that collects
 // all path, function names (converter.Function and editor.Function), and enumSymbol.
-type priorityContextInferrerHintsVisitor struct {
+type priorityContextInferrerHints struct {
 	paths        []path
 	functions    map[string]struct{}
 	enumsSymbols map[enumSymbol]struct{}
 }
 
-func newGrammarContextInferrerVisitor() priorityContextInferrerHintsVisitor {
-	return priorityContextInferrerHintsVisitor{
+func newGrammarContextInferrerVisitor() priorityContextInferrerHints {
+	return priorityContextInferrerHints{
 		paths:        []path{},
 		functions:    make(map[string]struct{}),
 		enumsSymbols: make(map[enumSymbol]struct{}),
 	}
 }
 
-func (v *priorityContextInferrerHintsVisitor) visitMathExprLiteral(_ *mathExprLiteral) {}
+func (v *priorityContextInferrerHints) visitMathExprLiteral(_ *mathExprLiteral) {}
 
-func (v *priorityContextInferrerHintsVisitor) visitEditor(e *editor) {
+func (v *priorityContextInferrerHints) visitEditor(e *editor) {
 	v.functions[e.Function] = struct{}{}
 }
 
-func (v *priorityContextInferrerHintsVisitor) visitConverter(c *converter) {
+func (v *priorityContextInferrerHints) visitConverter(c *converter) {
 	v.functions[c.Function] = struct{}{}
 }
 
-func (v *priorityContextInferrerHintsVisitor) visitValue(va *value) {
+func (v *priorityContextInferrerHints) visitValue(va *value) {
 	if va.Enum != nil {
 		v.enumsSymbols[*va.Enum] = struct{}{}
 	}
 }
 
-func (v *priorityContextInferrerHintsVisitor) visitPath(value *path) {
+func (v *priorityContextInferrerHints) visitPath(value *path) {
 	v.paths = append(v.paths, *value)
 }

pkg/ottl/context_inferrer_test.go

@@ -279,7 +279,14 @@ func Test_NewPriorityContextInferrer_InvalidStatement(t *testing.T) {
 	inferrer := newPriorityContextInferrer(componenttest.NewNopTelemetrySettings(), map[string]*priorityContextInferrerCandidate{})
 	statements := []string{"set(foo.field,"}
 	_, err := inferrer.inferFromStatements(statements)
-	require.ErrorContains(t, err, "unexpected token")
+	require.ErrorContains(t, err, "statement has invalid syntax")
+}
+
+func Test_NewPriorityContextInferrer_InvalidCondition(t *testing.T) {
+	inferrer := newPriorityContextInferrer(componenttest.NewNopTelemetrySettings(), map[string]*priorityContextInferrerCandidate{})
+	conditions := []string{"foo.field,"}
+	_, err := inferrer.inferFromConditions(conditions)
+	require.ErrorContains(t, err, "condition has invalid syntax")
 }
 
 func Test_NewPriorityContextInferrer_DefaultPriorityList(t *testing.T) {
@@ -487,3 +494,60 @@ func Test_NewPriorityContextInferrer_InferConditions_DefaultContextsOrder(t *tes
 		})
 	}
 }
+
+func Test_NewPriorityContextInferrer_Infer(t *testing.T) {
+	tests := []struct {
+		name       string
+		candidates map[string]*priorityContextInferrerCandidate
+		statements []string
+		conditions []string
+		expected   string
+	}{
+		{
+			name: "with statements",
+			candidates: map[string]*priorityContextInferrerCandidate{
+				"metric":   defaultDummyPriorityContextInferrerCandidate,
+				"resource": defaultDummyPriorityContextInferrerCandidate,
+			},
+			statements: []string{`set(resource.attributes["foo"], "bar")`},
+			expected:   "resource",
+		},
+		{
+			name: "with conditions",
+			candidates: map[string]*priorityContextInferrerCandidate{
+				"metric":   defaultDummyPriorityContextInferrerCandidate,
+				"resource": defaultDummyPriorityContextInferrerCandidate,
+			},
+			conditions: []string{
+				`IsMatch(metric.name, "^bar.*")`,
+				`IsMatch(metric.name, "^foo.*")`,
+			},
+			expected: "metric",
+		},
+		{
+			name: "with statements and conditions",
+			candidates: map[string]*priorityContextInferrerCandidate{
+				"metric":   defaultDummyPriorityContextInferrerCandidate,
+				"resource": defaultDummyPriorityContextInferrerCandidate,
+			},
+			statements: []string{`set(resource.attributes["foo"], "bar")`},
+			conditions: []string{
+				`IsMatch(metric.name, "^bar.*")`,
+				`IsMatch(metric.name, "^foo.*")`,
+			},
+			expected: "metric",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			inferrer := newPriorityContextInferrer(
+				componenttest.NewNopTelemetrySettings(),
+				tt.candidates,
+			)
+			inferredContext, err := inferrer.infer(tt.statements, tt.conditions)
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, inferredContext)
+		})
+	}
+}

pkg/ottl/parser_collection.go

@@ -320,29 +320,69 @@ func EnableParserCollectionModifiedPathsLogging[R any](enabled bool) ParserColle
 	}
 }
 
+type parseCollectionContextInferenceOptions struct {
+	conditions []string
+}
+
+// ParserCollectionContextInferenceOption allows configuring the context inference and use
+// this option with the supported parsing functions.
+//
+// Experimental: *NOTE* this API is subject to change or removal in the future.
+type ParserCollectionContextInferenceOption func(p *parseCollectionContextInferenceOptions)
+
+// WithContextInferenceConditions sets additional OTTL conditions to be used to enhance
+// the context inference process. This is particularly useful when the statements alone are
+// insufficient for determine the correct context, or when a less-specific context is desired.
+//
+// Experimental: *NOTE* this API is subject to change or removal in the future.
+func WithContextInferenceConditions(conditions []string) ParserCollectionContextInferenceOption {
+	return func(p *parseCollectionContextInferenceOptions) {
+		p.conditions = conditions
+	}
+}
+
 // ParseStatements parses the given statements into [R] using the configured context's ottl.Parser
 // and subsequently calling the ParsedStatementsConverter function.
 // The statement's context is automatically inferred from the [Path.Context] values, choosing the
 // highest priority context found.
 // If no contexts are present in the statements, or if the inferred value is not supported by
 // the [ParserCollection], it returns an error.
 // If parsing the statements fails, it returns the underlying [ottl.Parser.ParseStatements] error.
+// If the provided StatementsGetter also implements ContextInferenceHintsProvider, it uses the
+// additional OTTL conditions to enhance the context inference. This is particularly useful when
+// the statements alone are insufficient for determine the correct context, or if an less-specific
+// parser is desired.
 //
 // Experimental: *NOTE* this API is subject to change or removal in the future.
-func (pc *ParserCollection[R]) ParseStatements(statements StatementsGetter) (R, error) {
+func (pc *ParserCollection[R]) ParseStatements(statements StatementsGetter, options ...ParserCollectionContextInferenceOption) (R, error) {
 	statementsValues := statements.GetStatements()
-	inferredContext, err := pc.contextInferrer.inferFromStatements(statementsValues)
+
+	parseStatementsOpts := parseCollectionContextInferenceOptions{}
+	for _, opt := range options {
+		opt(&parseStatementsOpts)
+	}
+
+	conditionsValues := parseStatementsOpts.conditions
+
+	var inferredContext string
+	var err error
+	if len(conditionsValues) > 0 {
+		inferredContext, err = pc.contextInferrer.infer(statementsValues, conditionsValues)
+	} else {
+		inferredContext, err = pc.contextInferrer.inferFromStatements(statementsValues)
+	}
+
 	if err != nil {
-		return *new(R), fmt.Errorf("unable to infer a valid context (%+q) from statements %+q: %w", pc.supportedContextNames(), statementsValues, err)
+		return *new(R), fmt.Errorf("unable to infer a valid context (%+q) from statements %+q and conditions %+q: %w", pc.supportedContextNames(), statementsValues, conditionsValues, err)
 	}
 
 	if inferredContext == "" {
-		return *new(R), fmt.Errorf("unable to infer context from statements, path's first segment must be a valid context name: %+q, and at least one context must be capable of parsing all statements: %+q", pc.supportedContextNames(), statementsValues)
+		return *new(R), fmt.Errorf("unable to infer context from statements %+q and conditions %+q, path's first segment must be a valid context name %+q, and at least one context must be capable of parsing all statements", pc.supportedContextNames(), statementsValues, conditionsValues)
 	}
 
 	_, ok := pc.contextParsers[inferredContext]
 	if !ok {
-		return *new(R), fmt.Errorf(`context "%s" inferred from the statements %+q is not a supported context: %+q`, inferredContext, statementsValues, pc.supportedContextNames())
+		return *new(R), fmt.Errorf(`context "%s" inferred from the statements %+q and conditions %+q is not a supported context: %+q`, inferredContext, statementsValues, conditionsValues, pc.supportedContextNames())
 	}
 
 	return pc.ParseStatementsWithContext(inferredContext, statements, false)