[pkg/ottl] Adapt time parsing error messages to include the ctime directives (#38425)

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

This PR adapts the `Time` function to check for `time.ParseError`
errors. If such an error is received by the function, it wraps it into a
custom error type in order to include the provided ctime layout string
instead of the go-native layout string.

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

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

Adapted the unit tests of the `Time()` function

---------

Signed-off-by: Florian Bacher <[email protected]>

Author: bacherfl

.chloggen/time-parsing-error-messages.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: Improve time parsing error messages by including the ctime directive instead of the go time layout
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [35176]
+
+# (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: []

internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt.go

@@ -163,3 +163,17 @@ func Validate(format string) error {
 	}
 	return nil
 }
+
+// GetNativeSubstitutes analyzes the provided format string and returns a map where each
+// key is a Go native layout element (as used in time.Format) found in the format, and
+// each value is the corresponding ctime-like directive.
+func GetNativeSubstitutes(format string) map[string]string {
+	nativeDirectives := map[string]string{}
+	directives := ctimeRegexp.FindAllString(format, -1)
+	for _, directive := range directives {
+		if val, ok := ctimeSubstitutes[directive]; ok {
+			nativeDirectives[val] = directive
+		}
+	}
+	return nativeDirectives
+}

internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt_test.go

@@ -115,3 +115,41 @@ func TestValidate(t *testing.T) {
 		})
 	}
 }
+
+func TestGetNativeSubstitutes(t *testing.T) {
+	type args struct {
+		format string
+	}
+	tests := []struct {
+		name string
+		args args
+		want map[string]string
+	}{
+		{
+			name: "get ctime directives",
+			args: args{
+				format: "%Y-%m-%d %H:%M:%S.%f",
+			},
+			want: map[string]string{"01": "%m", "02": "%d", "04": "%M", "05": "%S", "15": "%H", "2006": "%Y", "999999": "%f"},
+		},
+		{
+			name: "format contains unsupported directive",
+			args: args{
+				format: "%C-%m-%d-%H-%M-%S.%L",
+			},
+			want: map[string]string{"01": "%m", "02": "%d", "04": "%M", "05": "%S", "15": "%H", "999": "%L"},
+		},
+		{
+			name: "format contains Go layout elements",
+			args: args{
+				format: "2006-%m-%d",
+			},
+			want: map[string]string{"01": "%m", "02": "%d"},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equalf(t, tt.want, GetNativeSubstitutes(tt.args.format), "GetNativeSubstitutes(%v)", tt.args.format)
+		})
+	}
+}

internal/coreinternal/timeutils/parser.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 
@@ -178,5 +179,37 @@ func ValidateLocale(locale string) error {
 	return fmt.Errorf("invalid locale '%s': %w", locale, err)
 }
 
+// GetStrptimeNativeSubstitutes analyzes the provided format string and returns a map
+// where each key is a Go native layout element (as used in time.Format) found in the
+// format, and each value is the corresponding ctime-like directive.
+func GetStrptimeNativeSubstitutes(format string) map[string]string {
+	return strptime.GetNativeSubstitutes(format)
+}
+
+type strptimeParseErr struct {
+	err               *time.ParseError
+	ctimeLayout       string
+	nativeSubstitutes map[string]string
+}
+
+func (e *strptimeParseErr) Error() string {
+	if e.err.Message == "" {
+		layoutElem, ok := e.nativeSubstitutes[e.err.LayoutElem]
+		if !ok {
+			layoutElem = e.err.LayoutElem
+		}
+		return "parsing time " +
+			strconv.Quote(e.err.Value) + " as " +
+			strconv.Quote(e.ctimeLayout) + ": cannot parse " +
+			strconv.Quote(e.err.ValueElem) + " as " +
+			strconv.Quote(layoutElem)
+	}
+	return "parsing time " + strconv.Quote(e.err.Value) + e.err.Message
+}
+
+func ToStrptimeParseError(err *time.ParseError, ctimeLayout string, nativeSubstitutes map[string]string) error {
+	return &strptimeParseErr{err, ctimeLayout, nativeSubstitutes}
+}
+
 // Allows tests to override with deterministic value
 var Now = time.Now

pkg/ottl/ottlfuncs/func_time.go

@@ -62,6 +62,8 @@ func Time[K any](inputTime ottl.StringGetter[K], format string, location ottl.Op
 		inputTimeLocale = &l
 	}
 
+	ctimeSubstitutes := timeutils.GetStrptimeNativeSubstitutes(format)
+
 	return func(ctx context.Context, tCtx K) (any, error) {
 		t, err := inputTime.Get(ctx, tCtx)
 		if err != nil {
@@ -77,6 +79,10 @@ func Time[K any](inputTime ottl.StringGetter[K], format string, location ottl.Op
 			timestamp, err = timeutils.ParseGotime(gotimeFormat, t, loc)
 		}
 		if err != nil {
+			var timeErr *time.ParseError
+			if errors.As(err, &timeErr) {
+				return nil, timeutils.ToStrptimeParseError(timeErr, format, ctimeSubstitutes)
+			}
 			return nil, err
 		}
 		return timestamp, nil

pkg/ottl/ottlfuncs/func_time_test.go

@@ -258,7 +258,7 @@ func Test_TimeError(t *testing.T) {
 				},
 			},
 			format:        "%Y/%m/%d",
-			expectedError: "cannot parse",
+			expectedError: `parsing time "11/11/11" as "%Y/%m/%d": cannot parse "11/11/11" as "%Y"`,
 		},
 		{
 			name: "invalid RFC3339 with no time",