[Proposal] log/logtest: Redesign 2nd edition

CHANGELOG.md

@@ -8,22 +8,32 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-### Removed
+### Added
 
-- Drop support for [Go 1.22]. (#6381, #6418)
+- Add `Recording`, `Scope`, `Record` types in `go.opentelemetry.io/otel/log/logtest`. (#6342)
+- Add `AssertEqual` function along with `IgnoreTimestamp` option in `go.opentelemetry.io/otel/log/logtest`. (#6342)
+- Add a testable example showing how `go.opentelemetry.io/otel/log/logtest` can be used. (#6342)
 
 ### Changed
 
 - ⚠️ Update `github.com/prometheus/client_golang` to `v1.21.1`, which changes the `NameValidationScheme` to `UTF8Validation`.
   This allows metrics names to keep original delimiters (e.g. `.`), rather than replacing with underscores.
   This can be reverted by setting `github.com/prometheus/common/model.NameValidationScheme` to `LegacyValidation` in `github.com/prometheus/common/model`. (#6433)
 - Initialize map with `len(keys)` in `NewAllowKeysFilter` and `NewDenyKeysFilter` to avoid unnecessary allocations in `go.opentelemetry.io/otel/attribute`. (#6455)
+- Change `Recorder.Result` to return `Recording`. (#6342)
+- `Recorder` no longer separately stores records emitted by loggers with the same instrumentation scope. (#6342)
 
 ### Fixes
 
 - Stop percent encoding header environment variables in `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc` and `go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`. (#6392)
 - Ensure the `noopSpan.tracerProvider` method is not inlined in `go.opentelemetry.io/otel/trace` so the `go.opentelemetry.io/auto` instrumentation can instrument non-recording spans. (#6456)
 
+### Removed
+
+- Drop support for [Go 1.22]. (#6381, #6418)
+- Remove `ScopeRecords`, `EmittedRecord`, `RecordFactory` types from `go.opentelemetry.io/otel/log/logtest`. (#6342)
+- Remove `AssertRecordEqual` function from `go.opentelemetry.io/otel/log/logtest`. (#6342)
+
 <!-- Released section -->
 <!-- Don't change this section unless doing release -->
 

log/go.mod

@@ -4,6 +4,7 @@ go 1.23.0
 
 require (
 	github.com/go-logr/logr v1.4.2
+	github.com/google/go-cmp v0.7.0
 	github.com/stretchr/testify v1.10.0
 	go.opentelemetry.io/otel v1.35.0
 )

log/logtest/assert.go

@@ -0,0 +1,75 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package logtest // import "go.opentelemetry.io/otel/log/logtest"
+
+import (
+	"context"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+
+	"go.opentelemetry.io/otel/log"
+)
+
+// TestingT reports failure messages.
+// [testing.T] implements this interface.
+type TestingT interface {
+	Errorf(format string, args ...any)
+}
+
+// AssertEqual asserts that the two concrete data-types from the logtest package are equal.
+func AssertEqual[T Recording | Record](t TestingT, want, got T, opts ...AssertOption) bool {
+	if h, ok := t.(interface{ Helper() }); ok {
+		h.Helper()
+	}
+
+	cmpOpts := []cmp.Option{
+		cmp.Comparer(func(x, y context.Context) bool { return x == y }),           // Compare context.
+		cmpopts.SortSlices(func(a, b log.KeyValue) bool { return a.Key < b.Key }), // Unordered compare of the key values.
+		cmpopts.EquateEmpty(), // Empty and nil collections are equal.
+	}
+
+	cfg := newAssertConfig(opts)
+	if cfg.ignoreTimestamp {
+		cmpOpts = append(cmpOpts, cmpopts.IgnoreTypes(time.Time{})) // Ignore Timestamps.
+	}
+
+	if diff := cmp.Diff(want, got, cmpOpts...); diff != "" {
+		t.Errorf("mismatch (-want +got):\n%s", diff)
+		return false
+	}
+	return true
+}
+
+type assertConfig struct {
+	ignoreTimestamp bool
+}
+
+func newAssertConfig(opts []AssertOption) assertConfig {
+	var cfg assertConfig
+	for _, opt := range opts {
+		cfg = opt.apply(cfg)
+	}
+	return cfg
+}
+
+// AssertOption allows for fine grain control over how AssertEqual operates.
+type AssertOption interface {
+	apply(cfg assertConfig) assertConfig
+}
+
+type fnOption func(cfg assertConfig) assertConfig
+
+func (fn fnOption) apply(cfg assertConfig) assertConfig {
+	return fn(cfg)
+}
+
+// IgnoreTimestamp disables checking if timestamps are different.
+func IgnoreTimestamp() AssertOption {
+	return fnOption(func(cfg assertConfig) assertConfig {
+		cfg.ignoreTimestamp = true
+		return cfg
+	})
+}

log/logtest/assert_test.go

@@ -0,0 +1,174 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package logtest
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"go.opentelemetry.io/otel/log"
+)
+
+var y2k = time.Date(2000, time.January, 1, 0, 0, 0, 0, time.UTC)
+
+type mockTestingT struct {
+	errors []string
+}
+
+func (m *mockTestingT) Errorf(format string, args ...any) {
+	m.errors = append(m.errors, format)
+}
+
+func TestAssertEqualRecording(t *testing.T) {
+	tests := []struct {
+		name string
+		a    Recording
+		b    Recording
+		opts []AssertOption
+		want bool
+	}{
+		{
+			name: "equal recordings",
+			a: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Timestamp: y2k, Context: context.Background(), Attributes: []log.KeyValue{log.Int("n", 1), log.String("foo", "bar")}},
+				},
+			},
+			b: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Timestamp: y2k, Context: context.Background(), Attributes: []log.KeyValue{log.String("foo", "bar"), log.Int("n", 1)}},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "different recordings",
+			a: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Attributes: []log.KeyValue{log.String("foo", "bar")}},
+				},
+			},
+			b: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Attributes: []log.KeyValue{log.Int("n", 1)}},
+				},
+			},
+			want: false,
+		},
+		{
+			name: "equal empty scopes",
+			a: Recording{
+				Scope{Name: t.Name()}: nil,
+			},
+			b: Recording{
+				Scope{Name: t.Name()}: []Record{},
+			},
+			want: true,
+		},
+		{
+			name: "equal empty attributes",
+			a: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Body: log.StringValue("msg"), Attributes: []log.KeyValue{}},
+				},
+			},
+			b: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Body: log.StringValue("msg"), Attributes: nil},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "ignore timestamp",
+			a: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Timestamp: y2k, Attributes: []log.KeyValue{log.String("foo", "bar")}},
+				},
+			},
+			b: Recording{
+				Scope{Name: t.Name()}: []Record{
+					{Timestamp: time.Now(), Attributes: []log.KeyValue{log.String("foo", "bar")}},
+				},
+			},
+			opts: []AssertOption{IgnoreTimestamp()},
+			want: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			mockT := &mockTestingT{}
+			result := AssertEqual(mockT, tc.a, tc.b, tc.opts...)
+			if result != tc.want {
+				t.Errorf("AssertEqual() = %v, want %v", result, tc.want)
+			}
+			if !tc.want && len(mockT.errors) == 0 {
+				t.Errorf("expected Errorf call but got none")
+			}
+		})
+	}
+}
+
+func TestAssertEqualRecord(t *testing.T) {
+	tests := []struct {
+		name string
+		a    Record
+		b    Record
+		opts []AssertOption
+		want bool
+	}{
+		{
+			name: "equal records",
+			a: Record{
+				Timestamp:  y2k,
+				Context:    context.Background(),
+				Attributes: []log.KeyValue{log.Int("n", 1), log.String("foo", "bar")},
+			},
+			b: Record{
+				Timestamp:  y2k,
+				Context:    context.Background(),
+				Attributes: []log.KeyValue{log.String("foo", "bar"), log.Int("n", 1)},
+			},
+			want: true,
+		},
+		{
+			name: "different records",
+			a: Record{
+				Attributes: []log.KeyValue{log.String("foo", "bar")},
+			},
+			b: Record{
+				Attributes: []log.KeyValue{log.Int("n", 1)},
+			},
+			want: false,
+		},
+		{
+			name: "ignore timestamp",
+			a: Record{
+				Timestamp:  y2k,
+				Attributes: []log.KeyValue{log.String("foo", "bar")},
+			},
+			b: Record{
+				Timestamp:  time.Now(),
+				Attributes: []log.KeyValue{log.String("foo", "bar")},
+			},
+			opts: []AssertOption{IgnoreTimestamp()},
+			want: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			mockT := &mockTestingT{}
+			result := AssertEqual(mockT, tc.a, tc.b, tc.opts...)
+			if result != tc.want {
+				t.Errorf("AssertEqual() = %v, want %v", result, tc.want)
+			}
+			if !tc.want && len(mockT.errors) == 0 {
+				t.Errorf("expected Errorf call but got none")
+			}
+		})
+	}
+}