[pkg/ottl]: Add Sort converter

.chloggen/ottl_sort_func.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 `Sort` function to sort array to ascending order or descending order
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [34200]
+
+# (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: [user]

pkg/ottl/e2e/e2e_test.go

@@ -619,6 +619,24 @@ func Test_e2e_converters(t *testing.T) {
 				tCtx.GetLogRecord().Attributes().PutStr("test", "d74ff0ee8da3b9806b18c877dbf29bbde50b5bd8e4dad7a3a725000feb82e8f1")
 			},
 		},
+		{
+			statement: `set(attributes["test"], Sort(Split(attributes["flags"], "|"), "desc"))`,
+			want: func(tCtx ottllog.TransformContext) {
+				s := tCtx.GetLogRecord().Attributes().PutEmptySlice("test")
+				s.AppendEmpty().SetStr("C")
+				s.AppendEmpty().SetStr("B")
+				s.AppendEmpty().SetStr("A")
+			},
+		},
+		{
+			statement: `set(attributes["test"], Sort([Int(11), Double(2.2), Double(-1)]))`,
+			want: func(tCtx ottllog.TransformContext) {
+				s := tCtx.GetLogRecord().Attributes().PutEmptySlice("test")
+				s.AppendEmpty().SetDouble(-1)
+				s.AppendEmpty().SetDouble(2.2)
+				s.AppendEmpty().SetInt(11)
+			},
+		},
 		{
 			statement: `set(span_id, SpanID(0x0000000000000000))`,
 			want: func(tCtx ottllog.TransformContext) {

pkg/ottl/go.mod

@@ -18,6 +18,7 @@ require (
 	go.opentelemetry.io/otel/sdk v1.28.0
 	go.opentelemetry.io/otel/trace v1.28.0
 	go.uber.org/goleak v1.3.0
+	go.uber.org/multierr v1.11.0
 	go.uber.org/zap v1.27.0
 	golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842
 	golang.org/x/net v0.27.0
@@ -43,7 +44,6 @@ require (
 	go.opentelemetry.io/otel/exporters/prometheus v0.50.0 // indirect
 	go.opentelemetry.io/otel/metric v1.28.0 // indirect
 	go.opentelemetry.io/otel/sdk/metric v1.28.0 // indirect
-	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/sys v0.22.0 // indirect
 	golang.org/x/text v0.16.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 // indirect

pkg/ottl/ottlfuncs/README.md

@@ -446,6 +446,7 @@ Available Converters:
 - [Seconds](#seconds)
 - [SHA1](#sha1)
 - [SHA256](#sha256)
+- [Sort](#sort)
 - [SpanID](#spanid)
 - [Split](#split)
 - [String](#string)
@@ -1206,6 +1207,37 @@ Examples:
 
 - `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.
+
+### Sort
+
+`Sort(target, Optional[order])`
+
+The `Sort` Converter sorts the `target` array in either ascending or descending order.
+
+`target` is a `pcommon.Slice` type field containing the elements to be sorted. 
+
+`order` is a string specifying the sort order. Must be either `asc` or `desc`. The default value is `asc`.
+
+The Sort Converter preserves the data type of the original elements while sorting. 
+The behavior varies based on the types of elements in the target slice:
+
+| Element Types | Sorting Behavior                    | Return Value |
+|---------------|-------------------------------------|--------------|
+| Integers | Sorts as integers                   | Sorted array of integers |
+| Doubles | Sorts as doubles                    | Sorted array of doubles |
+| Integers and doubles | Converts all to doubles, then sorts | Sorted array of integers and doubles |
+| Strings | Sorts as strings                    | Sorted array of strings |
+| Booleans | Converts all to strings, then sorts | Sorted array of booleans |
+| Mix of integers, doubles, booleans, and strings | Converts all to strings, then sorts | Sorted array of mixed types |
+| Any other types | N/A                                 | Returns an error |
+
+
+Examples:
+
+- `Sort(attributes["device.tags"])`
+- `Sort(attributes["device.tags"], "desc")`
+
 ### SpanID
 
 `SpanID(bytes)`

pkg/ottl/ottlfuncs/func_sort.go

@@ -0,0 +1,256 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package ottlfuncs // import "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/ottlfuncs"
+
+import (
+	"cmp"
+	"context"
+	"fmt"
+	"slices"
+	"strconv"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+	"go.uber.org/multierr"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
+)
+
+const (
+	sortAsc  = "asc"
+	sortDesc = "desc"
+)
+
+type SortArguments[K any] struct {
+	Target ottl.Getter[K]
+	Order  ottl.Optional[string]
+}
+
+func NewSortFactory[K any]() ottl.Factory[K] {
+	return ottl.NewFactory("Sort", &SortArguments[K]{}, createSortFunction[K])
+}
+
+func createSortFunction[K any](_ ottl.FunctionContext, oArgs ottl.Arguments) (ottl.ExprFunc[K], error) {
+	args, ok := oArgs.(*SortArguments[K])
+
+	if !ok {
+		return nil, fmt.Errorf("SortFactory args must be of type *SortArguments[K]")
+	}
+
+	order := sortAsc
+	if !args.Order.IsEmpty() {
+		o := args.Order.Get()
+		switch o {
+		case sortAsc, sortDesc:
+			order = o
+		default:
+			return nil, fmt.Errorf("invalid arguments: %s. Order should be either \"%s\" or \"%s\"", o, sortAsc, sortDesc)
+		}
+	}
+
+	return sort(args.Target, order), nil
+}
+
+func sort[K any](target ottl.Getter[K], order string) ottl.ExprFunc[K] {
+	return func(ctx context.Context, tCtx K) (any, error) {
+		val, err := target.Get(ctx, tCtx)
+		if err != nil {
+			return nil, err
+		}
+
+		switch v := val.(type) {
+		case pcommon.Slice:
+			return sortSlice(v, order)
+		case pcommon.Value:
+			if v.Type() == pcommon.ValueTypeSlice {
+				return sortSlice(v.Slice(), order)
+			}
+			return nil, fmt.Errorf("sort with unsupported type: '%s'. Target is not a list", v.Type().String())
+		case []any:
+			// handle Sort([1,2,3])
+			slice := pcommon.NewValueSlice().SetEmptySlice()
+			if err := slice.FromRaw(v); err != nil {
+				errs := multierr.Append(err, fmt.Errorf("sort with unsupported type: '%T'. Target is not a list of primitive types", v))
+				return nil, errs
+			}
+			return sortSlice(slice, order)
+		case []string:
+			// handle value from Split()
+			dup := makeCopy(v)
+			return sortTypedSlice(dup, order), nil
+		case []int64:
+			dup := makeCopy(v)
+			return sortTypedSlice(dup, order), nil
+		case []float64:
+			dup := makeCopy(v)
+			return sortTypedSlice(dup, order), nil
+		case []bool:
+			var strings []string
+			for _, b := range v {
+				strings = append(strings, strconv.FormatBool(b))
+			}
+
+			sortTypedSlice(strings, order)
+
+			bools := make([]bool, len(strings))
+			for i, s := range strings {
+				boolValue, _ := strconv.ParseBool(s)
+				bools[i] = boolValue
+			}
+			return bools, nil
+		default:
+			return nil, fmt.Errorf("sort with unsupported type: '%T'. Target is not a list", v)
+		}
+	}
+}
+
+// sortSlice sorts a pcommon.Slice based on the specified order.
+// It gets the common type for all elements in the slice and converts all elements to this common type, creating a new copy
+// Parameters:
+//   - slice: The pcommon.Slice to be sorted
+//   - order: The sort order. "asc" for ascending, "desc" for descending
+//
+// Returns:
+//   - A sorted slice as []any or the original pcommon.Slice
+//   - An error if an unsupported type is encountered
+func sortSlice(slice pcommon.Slice, order string) (any, error) {
+	length := slice.Len()
+	if length == 0 {
+		return slice, nil
+	}
+
+	commonType, ok := findCommonValueType(slice)
+	if !ok {
+		return slice, nil
+	}
+
+	switch commonType {
+	case pcommon.ValueTypeInt:
+		arr := makeConvertedCopy(slice, func(idx int) int64 {
+			return slice.At(idx).Int()
+		})
+		return sortConvertedSlice(arr, order), nil
+	case pcommon.ValueTypeDouble:
+		arr := makeConvertedCopy(slice, func(idx int) float64 {
+			s := slice.At(idx)
+			if s.Type() == pcommon.ValueTypeInt {
+				return float64(s.Int())
+			}
+
+			return s.Double()
+		})
+		return sortConvertedSlice(arr, order), nil
+	case pcommon.ValueTypeStr:
+		arr := makeConvertedCopy(slice, func(idx int) string {
+			return slice.At(idx).AsString()
+		})
+		return sortConvertedSlice(arr, order), nil
+	default:
+		return nil, fmt.Errorf("sort with unsupported type: '%T'", commonType)
+	}
+}
+
+type targetType interface {
+	~int64 | ~float64 | ~string
+}
+
+// findCommonValueType determines the most appropriate common type for all elements in a pcommon.Slice.
+// It returns two values:
+//   - A pcommon.ValueType representing the desired common type for all elements.
+//     Mixed Numeric types return ValueTypeDouble. Integer type returns ValueTypeInt. Double type returns ValueTypeDouble.
+//     String, Bool, Empty and mixed of the mentioned types return ValueTypeStr, as they require string conversion for comparison.
+//   - A boolean indicating whether a common type could be determined (true) or not (false).
+//     returns false for ValueTypeMap, ValueTypeSlice and ValueTypeBytes. They are unsupported types for sort.
+func findCommonValueType(slice pcommon.Slice) (pcommon.ValueType, bool) {
+	length := slice.Len()
+	if length == 0 {
+		return pcommon.ValueTypeEmpty, false
+	}
+
+	wantType := slice.At(0).Type()
+	wantStr := false
+	wantDouble := false
+
+	for i := 0; i < length; i++ {
+		value := slice.At(i)
+		currType := value.Type()
+
+		switch currType {
+		case pcommon.ValueTypeInt:
+			if wantType == pcommon.ValueTypeDouble {
+				wantDouble = true
+			}
+		case pcommon.ValueTypeDouble:
+			if wantType == pcommon.ValueTypeInt {
+				wantDouble = true
+			}
+		case pcommon.ValueTypeStr, pcommon.ValueTypeBool, pcommon.ValueTypeEmpty:
+			wantStr = true
+		default:
+			return pcommon.ValueTypeEmpty, false
+		}
+	}
+
+	if wantStr {
+		wantType = pcommon.ValueTypeStr
+	} else if wantDouble {
+		wantType = pcommon.ValueTypeDouble
+	}
+
+	return wantType, true
+}
+
+func makeCopy[T targetType](src []T) []T {
+	dup := make([]T, len(src))
+	copy(dup, src)
+	return dup
+}
+
+func sortTypedSlice[T targetType](arr []T, order string) []T {
+	if len(arr) == 0 {
+		return arr
+	}
+
+	slices.SortFunc(arr, func(a, b T) int {
+		if order == sortDesc {
+			return cmp.Compare(b, a)
+		}
+		return cmp.Compare(a, b)
+	})
+
+	return arr
+}
+
+type convertedValue[T targetType] struct {
+	value         T
+	originalValue any
+}
+
+func makeConvertedCopy[T targetType](slice pcommon.Slice, converter func(idx int) T) []convertedValue[T] {
+	length := slice.Len()
+	var out []convertedValue[T]
+	for i := 0; i < length; i++ {
+		cv := convertedValue[T]{
+			value:         converter(i),
+			originalValue: slice.At(i).AsRaw(),
+		}
+		out = append(out, cv)
+	}
+	return out
+}
+
+func sortConvertedSlice[T targetType](cvs []convertedValue[T], order string) []any {
+	slices.SortFunc(cvs, func(a, b convertedValue[T]) int {
+		if order == sortDesc {
+			return cmp.Compare(b.value, a.value)
+		}
+		return cmp.Compare(a.value, b.value)
+	})
+
+	var out []any
+	for _, cv := range cvs {
+		out = append(out, cv.originalValue)
+	}
+
+	return out
+}