Add MurmurHash3 function to convert the target to a hexadecimal

string of the murmurHash3 hash/digest

Fix: open-telemetry#34077

Author: kaisecheng

.chloggen/ottl_murmurhash3_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 `MurmurHash3` function to convert the `target` to a hexadecimal string of the murmurHash3 hash/digest"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [34077]
+
+# (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

@@ -510,6 +510,18 @@ func Test_e2e_converters(t *testing.T) {
 				tCtx.GetLogRecord().Attributes().PutDouble("test", 60)
 			},
 		},
+		{
+			statement: `set(attributes["test"], MurmurHash3("Hello World"))`,
+			want: func(tCtx ottllog.TransformContext) {
+				tCtx.GetLogRecord().Attributes().PutStr("test", "dbc2a0c1ab26631a27b4c09fcf1fe683")
+			},
+		},
+		{
+			statement: `set(attributes["test"], MurmurHash3("Hello World", version="32"))`,
+			want: func(tCtx ottllog.TransformContext) {
+				tCtx.GetLogRecord().Attributes().PutStr("test", "ce837619")
+			},
+		},
 		{
 			statement: `set(attributes["test"], Nanoseconds(Duration("1ms")))`,
 			want: func(tCtx ottllog.TransformContext) {

pkg/ottl/go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/json-iterator/go v1.1.12
 	github.com/open-telemetry/opentelemetry-collector-contrib/internal/coreinternal v0.105.0
 	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatatest v0.105.0
+	github.com/spaolacci/murmur3 v1.1.0
 	github.com/stretchr/testify v1.9.0
 	go.opentelemetry.io/collector/component v0.105.1-0.20240717163034-43ed6184f9fe
 	go.opentelemetry.io/collector/pdata v1.12.1-0.20240716231837-5753a58f712b

pkg/ottl/go.sum

@@ -436,6 +436,7 @@ Available Converters:
 - [Minute](#minute)
 - [Minutes](#minutes)
 - [Month](#month)
+- [MurmurHash3](#murmurhash3)
 - [Nanoseconds](#nanoseconds)
 - [Now](#now)
 - [ParseCSV](#parsecsv)
@@ -947,6 +948,23 @@ Examples:
 
 - `Month(Now())`
 
+### MurmurHash3
+
+`MurmurHash3(target, Optional[version])`
+
+The `MurmurHash3` Converter converts the `target` to a hexadecimal string of murmurHash3 hash/digest
+
+`target` is either a path expression to a telemetry field to retrieve or a literal.
+
+`version` is an optional string. MurmurHash3 has 32-bit and 128-bit version. The default value is `128`. Available values are `32` and `128`.
+
+The returned type is `string`.
+
+Examples:
+
+- `MurmurHash3(attributes["device.name"])`
+- `MurmurHash3("sometext", version="32")`
+
 ### Nanoseconds
 
 `Nanoseconds(value)`

pkg/ottl/ottlfuncs/README.md

@@ -0,0 +1,75 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package ottlfuncs // import "github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl/ottlfuncs"
+
+import (
+	"context"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
+	"github.com/spaolacci/murmur3"
+)
+
+const (
+	v32  = "32"
+	v128 = "128" // default
+)
+
+type MurmurHash3Arguments[K any] struct {
+	Target  ottl.StringGetter[K]
+	Version ottl.Optional[string] // 32-bit or 128-bit
+}
+
+func NewMurmurHash3Factory[K any]() ottl.Factory[K] {
+	return ottl.NewFactory("MurmurHash3", &MurmurHash3Arguments[K]{}, createMurmurHash3Function[K])
+}
+
+func createMurmurHash3Function[K any](_ ottl.FunctionContext, oArgs ottl.Arguments) (ottl.ExprFunc[K], error) {
+	args, ok := oArgs.(*MurmurHash3Arguments[K])
+
+	if !ok {
+		return nil, fmt.Errorf("MurmurHash3Factory args must be of type *MurmurHash3Arguments[K]")
+	}
+
+	version := v128
+	if !args.Version.IsEmpty() {
+		if (args.Version.Get() != v32) && (args.Version.Get() != v128) {
+			return nil, fmt.Errorf("invalid arguments: %s. Version should be either \"32\" or \"128\"", args.Version.Get())
+		}
+		version = args.Version.Get()
+	}
+
+	return MurmurHash3HexString(args.Target, version)
+}
+
+// MurmurHash3HexString return the hex value of the hash in little-endian.
+// MurmurHash3 by Austin Appleby is endian-sensitive. Other languages like python use little-endian for all architectures.
+// The Go lib `spaolacci/murmur3` has a couple of issues related to endianness compatibility across languages.
+// This function uses little-endian for consistency and returns hash value in hexadecimal number.
+func MurmurHash3HexString[K any](target ottl.StringGetter[K], version string) (ottl.ExprFunc[K], error) {
+	return func(ctx context.Context, tCtx K) (any, error) {
+		val, err := target.Get(ctx, tCtx)
+		if err != nil {
+			return nil, err
+		}
+
+		switch version {
+		case v32:
+			h := murmur3.Sum32([]byte(val))
+			b := make([]byte, 4)
+			binary.LittleEndian.PutUint32(b, h)
+			return hex.EncodeToString(b), nil
+		case v128:
+			h1, h2 := murmur3.Sum128([]byte(val))
+			b := make([]byte, 16)
+			binary.LittleEndian.PutUint64(b[:8], h1)
+			binary.LittleEndian.PutUint64(b[8:], h2)
+			return hex.EncodeToString(b), nil
+		default:
+			return nil, fmt.Errorf("invalid argument: %s", version)
+		}
+	}, nil
+}

pkg/ottl/ottlfuncs/func_murmurhash3.go

@@ -0,0 +1,125 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package ottlfuncs
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl"
+)
+
+func Test_MurmurHash3(t *testing.T) {
+	tests := []struct {
+		name        string
+		oArgs       ottl.Arguments
+		expected    string
+		createError string
+		funcError   string
+	}{
+		{
+			name: "string",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return "Hello World", nil
+					},
+				},
+			},
+			expected: "dbc2a0c1ab26631a27b4c09fcf1fe683",
+		},
+		{
+			name: "empty string",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return "", nil
+					},
+				},
+				Version: ottl.NewTestingOptional[string]("128"),
+			},
+			expected: "00000000000000000000000000000000",
+		},
+		{
+			name: "string in v128",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return "Hello World", nil
+					},
+				},
+				Version: ottl.NewTestingOptional[string]("128"),
+			},
+			expected: "dbc2a0c1ab26631a27b4c09fcf1fe683",
+		},
+		{
+			name: "string in v32",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return "Hello World", nil
+					},
+				},
+				Version: ottl.NewTestingOptional[string]("32"),
+			},
+			expected: "ce837619",
+		},
+		{
+			name: "invalid version",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return "Hello World", nil
+					},
+				},
+				Version: ottl.NewTestingOptional[string]("66"),
+			},
+			createError: "invalid arguments: 66",
+		},
+		{
+			name: "non-string",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return 10, nil
+					},
+				},
+			},
+			funcError: "expected string but got int",
+		},
+		{
+			name: "nil",
+			oArgs: &MurmurHash3Arguments[any]{
+				Target: ottl.StandardStringGetter[any]{
+					Getter: func(_ context.Context, _ any) (any, error) {
+						return nil, nil
+					},
+				},
+			},
+			funcError: "expected string but got nil",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			exprFunc, err := createMurmurHash3Function[any](ottl.FunctionContext{}, tt.oArgs)
+			if tt.createError != "" {
+				require.ErrorContains(t, err, tt.createError)
+				return
+			}
+
+			assert.NoError(t, err)
+
+			result, err := exprFunc(nil, nil)
+			if tt.funcError != "" {
+				require.ErrorContains(t, err, tt.funcError)
+				return
+			}
+
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

pkg/ottl/ottlfuncs/func_murmurhash3_test.go

@@ -61,6 +61,7 @@ func converters[K any]() []ottl.Factory[K] {
 		NewMinuteFactory[K](),
 		NewMinutesFactory[K](),
 		NewMonthFactory[K](),
+		NewMurmurHash3Factory[K](),
 		NewNanosecondsFactory[K](),
 		NewNowFactory[K](),
 		NewParseCSVFactory[K](),