[dependency] sdk/log/xlog: Add FilterProcessor and EnabledParameters

CHANGELOG.md

@@ -31,6 +31,13 @@ The next release will require at least [Go 1.23].
 - Document the pitfalls of using `Resource` as a comparable type.
   `Resource.Equal` and `Resource.Equivalent` should be used instead. (#6272)
 - Support [Go 1.24]. (#6304)
+- Make the initial release of `go.opentelemetry.io/otel/sdk/log/xlog`.
+  This new module contains experimental features of the OpenTelemetry Logs SDK.
+  It replaces `go.opentelemetry.io/otel/sdk/log/internal/x`.
+  This module is unstable and breaking changes may be introduced.
+  See our [versioning policy](VERSIONING.md) for more information about these stability guarantees. (#6271)
+- Add `FilterProcessor` and `EnabledParameters` in `go.opentelemetry.io/otel/sdk/log/xlog` .
+  Compared to previous version it additionally gives the possibility to filter by resource and instrumentation scope. (#6271)
 
 ### Changed
 

exporters/otlp/otlplog/otlploggrpc/go.mod

@@ -26,6 +26,7 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/otel/metric v1.34.0 // indirect
+	go.opentelemetry.io/otel/sdk/log/xlog v0.0.0-00010101000000-000000000000 // indirect
 	golang.org/x/net v0.35.0 // indirect
 	golang.org/x/sys v0.30.0 // indirect
 	golang.org/x/text v0.22.0 // indirect
@@ -44,3 +45,5 @@ replace go.opentelemetry.io/otel/log => ../../../../log
 replace go.opentelemetry.io/otel/trace => ../../../../trace
 
 replace go.opentelemetry.io/otel/metric => ../../../../metric
+
+replace go.opentelemetry.io/otel/sdk/log/xlog => ../../../../sdk/log/xlog

exporters/otlp/otlplog/otlploghttp/go.mod

@@ -24,6 +24,7 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/otel/metric v1.34.0 // indirect
+	go.opentelemetry.io/otel/sdk/log/xlog v0.0.0-00010101000000-000000000000 // indirect
 	golang.org/x/net v0.35.0 // indirect
 	golang.org/x/sys v0.30.0 // indirect
 	golang.org/x/text v0.22.0 // indirect
@@ -44,3 +45,5 @@ replace go.opentelemetry.io/otel/sdk => ../../../../sdk
 replace go.opentelemetry.io/otel/metric => ../../../../metric
 
 replace go.opentelemetry.io/otel/log => ../../../../log
+
+replace go.opentelemetry.io/otel/sdk/log/xlog => ../../../../sdk/log/xlog

exporters/stdout/stdoutlog/go.mod

@@ -19,6 +19,7 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/otel/metric v1.34.0 // indirect
+	go.opentelemetry.io/otel/sdk/log/xlog v0.0.0-00010101000000-000000000000 // indirect
 	golang.org/x/sys v0.30.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
@@ -34,3 +35,5 @@ replace go.opentelemetry.io/otel/trace => ../../../trace
 replace go.opentelemetry.io/otel/sdk => ../../../sdk
 
 replace go.opentelemetry.io/otel/metric => ../../../metric
+
+replace go.opentelemetry.io/otel/sdk/log/xlog => ../../../sdk/log/xlog

log/logger.go

@@ -33,9 +33,13 @@ type Logger interface {
 	// Enabled returns whether the Logger emits for the given context and
 	// param.
 	//
-	// The passed param is likely to be a partial record with only the
-	// bridge-relevant information being provided (e.g a param with only the
-	// Severity set). If a Logger needs more information than is provided, it
+	// This is useful for users that want to know if a [Record]
+	// will be processed or dropped before they perform complex operations to
+	// construct the [Record].
+	//
+	// The passed param is likely to be a partial record information being
+	// provided (e.g a param with only the Severity set).
+	// If a Logger needs more information than is provided, it
 	// is said to be in an indeterminate state (see below).
 	//
 	// The returned value will be true when the Logger will emit for the
@@ -46,7 +50,7 @@ type Logger interface {
 	// exist (e.g. performance, correctness).
 	//
 	// The param should not be held by the implementation. A copy should be
-	// made if the record needs to be held after the call returns.
+	// made if the param needs to be held after the call returns.
 	//
 	// Implementations of this method need to be safe for a user to call
 	// concurrently.

sdk/log/doc.go

@@ -33,7 +33,7 @@ at a single endpoint their origin is decipherable.
 See [go.opentelemetry.io/otel/log] for more information about
 the OpenTelemetry Logs Bridge API.
 
-See [go.opentelemetry.io/otel/sdk/log/internal/x] for information about the
+See [go.opentelemetry.io/otel/sdk/log/xlog] for information about the
 experimental features.
 */
 package log // import "go.opentelemetry.io/otel/sdk/log"

sdk/log/example_test.go

@@ -12,6 +12,7 @@ import (
 	logapi "go.opentelemetry.io/otel/log"
 	"go.opentelemetry.io/otel/log/global"
 	"go.opentelemetry.io/otel/sdk/log"
+	"go.opentelemetry.io/otel/sdk/log/xlog"
 )
 
 // Initialize OpenTelemetry Logs SDK and setup logging using a log bridge.
@@ -52,6 +53,7 @@ func Example() {
 }
 
 // Use a processor that filters out records based on the provided context.
+// It also demonstrates the use of experimental [xlog.FilterProcessor].
 func ExampleProcessor_filtering() {
 	// Existing processor that emits telemetry.
 	var processor log.Processor = log.NewBatchProcessor(nil)
@@ -84,14 +86,12 @@ type ContextFilterProcessor struct {
 	log.Processor
 
 	lazyFilter sync.Once
-	// Use the experimental FilterProcessor interface
-	// (go.opentelemetry.io/otel/sdk/log/internal/x).
-	filter filter
+	// Support the experimental FilterProcessor interface for the embedded processor.
+	filter xlog.FilterProcessor
 }
 
-type filter interface {
-	Enabled(ctx context.Context, param logapi.EnabledParameters) bool
-}
+// Compile time check.
+var _ xlog.FilterProcessor = (*ContextFilterProcessor)(nil)
 
 func (p *ContextFilterProcessor) OnEmit(ctx context.Context, record *log.Record) error {
 	if ignoreLogs(ctx) {
@@ -100,9 +100,9 @@ func (p *ContextFilterProcessor) OnEmit(ctx context.Context, record *log.Record)
 	return p.Processor.OnEmit(ctx, record)
 }
 
-func (p *ContextFilterProcessor) Enabled(ctx context.Context, param logapi.EnabledParameters) bool {
+func (p *ContextFilterProcessor) Enabled(ctx context.Context, param xlog.EnabledParameters) bool {
 	p.lazyFilter.Do(func() {
-		if f, ok := p.Processor.(filter); ok {
+		if f, ok := p.Processor.(xlog.FilterProcessor); ok {
 			p.filter = f
 		}
 	})

sdk/log/go.mod

@@ -10,6 +10,7 @@ require (
 	go.opentelemetry.io/otel v1.34.0
 	go.opentelemetry.io/otel/log v0.10.0
 	go.opentelemetry.io/otel/sdk v1.34.0
+	go.opentelemetry.io/otel/sdk/log/xlog v0.0.0-00010101000000-000000000000
 	go.opentelemetry.io/otel/trace v1.34.0
 )
 
@@ -29,6 +30,8 @@ replace go.opentelemetry.io/otel/trace => ../../trace
 
 replace go.opentelemetry.io/otel/sdk => ../
 
+replace go.opentelemetry.io/otel/sdk/log/xlog => ./xlog
+
 replace go.opentelemetry.io/otel/log => ../../log
 
 replace go.opentelemetry.io/otel => ../..

sdk/log/logger.go

@@ -11,7 +11,7 @@ import (
 	"go.opentelemetry.io/otel/log"
 	"go.opentelemetry.io/otel/log/embedded"
 	"go.opentelemetry.io/otel/sdk/instrumentation"
-	"go.opentelemetry.io/otel/sdk/log/internal/x"
+	"go.opentelemetry.io/otel/sdk/log/xlog"
 	"go.opentelemetry.io/otel/trace"
 )
 
@@ -50,14 +50,22 @@ func (l *logger) Emit(ctx context.Context, r log.Record) {
 // processed, true will be returned by default. A value of false will only be
 // returned if it can be positively verified that no Processor will process.
 func (l *logger) Enabled(ctx context.Context, param log.EnabledParameters) bool {
-	// If there are more Processors than FilterProcessors we cannot be sure
-	// that all Processors will drop the record. Therefore, return true.
+	p := xlog.EnabledParameters{
+		Resource:             *l.provider.resource,
+		InstrumentationScope: l.instrumentationScope,
+		Severity:             param.Severity,
+	}
+
+	// If there are more Processors than FilterProcessors,
+	// which means not all Processors are FilterProcessors,
+	// we cannot be sure that all Processors will drop the record.
+	// Therefore, return true.
 	//
 	// If all Processors are FilterProcessors, check if any is enabled.
-	return len(l.provider.processors) > len(l.provider.fltrProcessors) || anyEnabled(ctx, param, l.provider.fltrProcessors)
+	return len(l.provider.processors) > len(l.provider.fltrProcessors) || anyEnabled(ctx, p, l.provider.fltrProcessors)
 }
 
-func anyEnabled(ctx context.Context, param log.EnabledParameters, fltrs []x.FilterProcessor) bool {
+func anyEnabled(ctx context.Context, param xlog.EnabledParameters, fltrs []xlog.FilterProcessor) bool {
 	for _, f := range fltrs {
 		if f.Enabled(ctx, param) {
 			// At least one Processor will process the Record.

sdk/log/logger_test.go

@@ -14,6 +14,7 @@ import (
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/log"
 	"go.opentelemetry.io/otel/sdk/instrumentation"
+	"go.opentelemetry.io/otel/sdk/log/xlog"
 	"go.opentelemetry.io/otel/sdk/resource"
 	"go.opentelemetry.io/otel/trace"
 )
@@ -224,11 +225,17 @@ func TestLoggerEnabled(t *testing.T) {
 	p1 := newFltrProcessor("1", true)
 	p2WithDisabled := newFltrProcessor("2", false)
 
+	emptyResource := resource.Empty()
+	res := resource.NewSchemaless(attribute.String("key", "value"))
+
 	testCases := []struct {
-		name     string
-		logger   *logger
-		ctx      context.Context
-		expected bool
+		name             string
+		logger           *logger
+		ctx              context.Context
+		expected         bool
+		expectedP0Params []xlog.EnabledParameters
+		expectedP1Params []xlog.EnabledParameters
+		expectedP2Params []xlog.EnabledParameters
 	}{
 		{
 			name:     "NoProcessors",
@@ -241,41 +248,63 @@ func TestLoggerEnabled(t *testing.T) {
 			logger: newLogger(NewLoggerProvider(
 				WithProcessor(p0),
 				WithProcessor(p1),
-			), instrumentation.Scope{}),
+				WithResource(res),
+			), instrumentation.Scope{Name: "scope"}),
 			ctx:      context.Background(),
 			expected: true,
+			expectedP0Params: []xlog.EnabledParameters{{
+				Resource:             *res,
+				InstrumentationScope: instrumentation.Scope{Name: "scope"},
+			}},
+			expectedP1Params: nil,
 		},
 		{
 			name: "WithDisabledProcessors",
 			logger: newLogger(NewLoggerProvider(
 				WithProcessor(p2WithDisabled),
+				WithResource(emptyResource),
 			), instrumentation.Scope{}),
-			ctx:      context.Background(),
-			expected: false,
+			ctx:              context.Background(),
+			expected:         false,
+			expectedP2Params: []xlog.EnabledParameters{{}},
 		},
 		{
 			name: "ContainsDisabledProcessor",
 			logger: newLogger(NewLoggerProvider(
 				WithProcessor(p2WithDisabled),
 				WithProcessor(p0),
+				WithResource(emptyResource),
 			), instrumentation.Scope{}),
-			ctx:      context.Background(),
-			expected: true,
+			ctx:              context.Background(),
+			expected:         true,
+			expectedP2Params: []xlog.EnabledParameters{{}},
+			expectedP0Params: []xlog.EnabledParameters{{}},
 		},
 		{
 			name: "WithNilContext",
 			logger: newLogger(NewLoggerProvider(
 				WithProcessor(p0),
 				WithProcessor(p1),
+				WithResource(emptyResource),
 			), instrumentation.Scope{}),
-			ctx:      nil,
-			expected: true,
+			ctx:              nil,
+			expected:         true,
+			expectedP0Params: []xlog.EnabledParameters{{}},
+			expectedP1Params: nil,
 		},
 	}
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
+			// Clean up the records before the test.
+			p0.params = nil
+			p1.params = nil
+			p2WithDisabled.params = nil
+
 			assert.Equal(t, tc.expected, tc.logger.Enabled(tc.ctx, log.EnabledParameters{}))
+			assert.Equal(t, tc.expectedP0Params, p0.params)
+			assert.Equal(t, tc.expectedP1Params, p1.params)
+			assert.Equal(t, tc.expectedP2Params, p2WithDisabled.params)
 		})
 	}
 }