sdk/log: Scaffolding (#5068)

.github/dependabot.yml

@@ -253,6 +253,15 @@ updates:
     schedule:
       interval: weekly
       day: sunday
+  - package-ecosystem: gomod
+    directory: /sdk/log
+    labels:
+      - dependencies
+      - go
+      - Skip Changelog
+    schedule:
+      interval: weekly
+      day: sunday
   - package-ecosystem: gomod
     directory: /sdk/metric
     labels:

sdk/log/DESIGN.md

@@ -73,7 +73,6 @@ can be configured using following options:
 //
 // If the OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, no limit 128 will be used.
@@ -88,7 +87,6 @@ func WithAttributeCountLimit(limit int) LoggerProviderOption
 //
 // If the OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, no limit (-1) will be used.
@@ -199,7 +197,6 @@ type BatchingOption interface { /* ... */ }
 //
 // If the OTEL_BLRP_MAX_QUEUE_SIZE environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_BLRP_MAX_QUEUE_SIZE will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, 2048 will be used.
@@ -210,7 +207,6 @@ func WithMaxQueueSize(max int) BatchingOption
 //
 // If the OTEL_BSP_SCHEDULE_DELAY environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_BSP_SCHEDULE_DELAY will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, 1s will be used.
@@ -221,7 +217,6 @@ func WithExportInterval(d time.Duration) BatchingOption
 //
 // If the OTEL_BSP_EXPORT_TIMEOUT environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_BSP_EXPORT_TIMEOUT will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, 30s will be used.
@@ -232,7 +227,6 @@ func WithExportTimeout(d time.Duration) BatchingOption
 //
 // If the OTEL_BSP_MAX_EXPORT_BATCH_SIZE environment variable is set,
 // and this option is not passed, that variable value will be used.
-// If both are set, OTEL_BSP_MAX_EXPORT_BATCH_SIZE will take precedence.
 //
 // By default, if an environment variable is not set, and this option is not
 // passed, 512 will be used.

sdk/log/batch.go

@@ -0,0 +1,119 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package log // import "go.opentelemetry.io/otel/sdk/log"
+
+import (
+	"context"
+	"time"
+)
+
+// Compile-time check BatchingProcessor implements Processor.
+var _ Processor = (*BatchingProcessor)(nil)
+
+// BatchingProcessor is an processor that asynchronously exports batches of log records.
+type BatchingProcessor struct{}
+
+type batcherConfig struct{}
+
+// NewBatchingProcessor decorates the provided exporter
+// so that the log records are batched before exporting.
+//
+// All of the exporter's methods are called from a single dedicated
+// background goroutine. Therefore, the expoter does not need to
+// be concurrent safe.
+func NewBatchingProcessor(exporter Exporter, opts ...BatchingOption) *BatchingProcessor {
+	// TODO (#5063): Implement.
+	return nil
+}
+
+// OnEmit batches provided log record.
+func (b *BatchingProcessor) OnEmit(ctx context.Context, r Record) error {
+	// TODO (#5063): Implement.
+	return nil
+}
+
+// Shutdown flushes queued log records and shuts down the decorated expoter.
+func (b *BatchingProcessor) Shutdown(ctx context.Context) error {
+	// TODO (#5063): Implement.
+	return nil
+}
+
+// ForceFlush flushes queued log records and flushes the decorated expoter.
+func (b *BatchingProcessor) ForceFlush(ctx context.Context) error {
+	// TODO (#5063): Implement.
+	return nil
+}
+
+// BatchingOption applies a configuration to a BatchingProcessor.
+type BatchingOption interface {
+	apply(batcherConfig) batcherConfig
+}
+
+type batchingOptionFunc func(batcherConfig) batcherConfig
+
+func (fn batchingOptionFunc) apply(c batcherConfig) batcherConfig {
+	return fn(c)
+}
+
+// WithMaxQueueSize sets the maximum queue size used by the Batcher.
+// After the size is reached log records are dropped.
+//
+// If the OTEL_BLRP_MAX_QUEUE_SIZE environment variable is set,
+// and this option is not passed, that variable value will be used.
+//
+// By default, if an environment variable is not set, and this option is not
+// passed, 2048 will be used.
+// The default value is also used when the provided value is less than one.
+func WithMaxQueueSize(max int) BatchingOption {
+	return batchingOptionFunc(func(cfg batcherConfig) batcherConfig {
+		// TODO (#5063): Implement.
+		return cfg
+	})
+}
+
+// WithExportInterval sets the maximum duration between batched exports.
+//
+// If the OTEL_BSP_SCHEDULE_DELAY environment variable is set,
+// and this option is not passed, that variable value will be used.
+//
+// By default, if an environment variable is not set, and this option is not
+// passed, 1s will be used.
+// The default value is also used when the provided value is less than one.
+func WithExportInterval(d time.Duration) BatchingOption {
+	return batchingOptionFunc(func(cfg batcherConfig) batcherConfig {
+		// TODO (#5063): Implement.
+		return cfg
+	})
+}
+
+// WithExportTimeout sets the duration after which a batched export is canceled.
+//
+// If the OTEL_BSP_EXPORT_TIMEOUT environment variable is set,
+// and this option is not passed, that variable value will be used.
+//
+// By default, if an environment variable is not set, and this option is not
+// passed, 30s will be used.
+// The default value is also used when the provided value is less than one.
+func WithExportTimeout(d time.Duration) BatchingOption {
+	return batchingOptionFunc(func(cfg batcherConfig) batcherConfig {
+		// TODO (#5063): Implement.
+		return cfg
+	})
+}
+
+// WithExportMaxBatchSize sets the maximum batch size of every export.
+// A batch will be split into multiple exports to not exceed this size.
+//
+// If the OTEL_BSP_MAX_EXPORT_BATCH_SIZE environment variable is set,
+// and this option is not passed, that variable value will be used.
+//
+// By default, if an environment variable is not set, and this option is not
+// passed, 512 will be used.
+// The default value is also used when the provided value is less than one.
+func WithExportMaxBatchSize(max int) BatchingOption {
+	return batchingOptionFunc(func(cfg batcherConfig) batcherConfig {
+		// TODO (#5063): Implement.
+		return cfg
+	})
+}

sdk/log/doc.go

@@ -0,0 +1,9 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// TODO (#5065): Expand documentation stub.
+
+/*
+Package log provides the OpenTelemetry Logs SDK.
+*/
+package log // import "go.opentelemetry.io/otel/sdk/log"

sdk/log/exporter.go

@@ -0,0 +1,42 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package log // import "go.opentelemetry.io/otel/sdk/log"
+
+import (
+	"context"
+)
+
+// Exporter handles the delivery of log records to external receivers.
+type Exporter interface {
+	// Export transmits log records to a receiver.
+	//
+	// The deadline or cancellation of the passed context must be honored. An
+	// appropriate error should be returned in these situations.
+	//
+	// All retry logic must be contained in this function. The SDK does not
+	// implement any retry logic. All errors returned by this function are
+	// considered unrecoverable and will be reported to a configured error
+	// Handler.
+	//
+	// Implementations must not retain the records slice.
+	//
+	// Before modifying a Record, the implementation must use Record.Clone
+	// to create a copy that shares no state with the original.
+	Export(ctx context.Context, records []Record) error
+	// Shutdown is called when the SDK shuts down. Any cleanup or release of
+	// resources held by the exporter should be done in this call.
+	//
+	// The deadline or cancellation of the passed context must be honored. An
+	// appropriate error should be returned in these situations.
+	//
+	// After Shutdown is called, calls to Export, Shutdown, or ForceFlush
+	// should perform no operation and return nil error.
+	Shutdown(ctx context.Context) error
+	// ForceFlush exports log records to the configured Exporter that have not yet
+	// been exported.
+	//
+	// The deadline or cancellation of the passed context must be honored. An
+	// appropriate error should be returned in these situations.
+	ForceFlush(ctx context.Context) error
+}

sdk/log/go.mod

@@ -0,0 +1,27 @@
+module go.opentelemetry.io/otel/sdk/log
+
+go 1.21
+
+require (
+	go.opentelemetry.io/otel/log v0.0.1-alpha
+	go.opentelemetry.io/otel/sdk v1.24.0
+	go.opentelemetry.io/otel/trace v1.24.0
+)
+
+require (
+	github.com/go-logr/logr v1.4.1 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	go.opentelemetry.io/otel v1.24.0 // indirect
+	go.opentelemetry.io/otel/metric v1.24.0 // indirect
+	golang.org/x/sys v0.18.0 // indirect
+)
+
+replace go.opentelemetry.io/otel/metric => ../../metric
+
+replace go.opentelemetry.io/otel/trace => ../../trace
+
+replace go.opentelemetry.io/otel/sdk => ../
+
+replace go.opentelemetry.io/otel/log => ../../log
+
+replace go.opentelemetry.io/otel => ../..

sdk/log/go.sum

@@ -0,0 +1,17 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.1 h1:pKouT5E8xu9zeFC39JXRDukb6JFQPXM5p5I91188VAQ=
+github.com/go-logr/logr v1.4.1/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
+golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

sdk/log/logger.go

@@ -0,0 +1,22 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package log // import "go.opentelemetry.io/otel/sdk/log"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/log"
+	"go.opentelemetry.io/otel/log/embedded"
+)
+
+// Compile-time check logger implements log.Logger.
+var _ log.Logger = (*logger)(nil)
+
+type logger struct {
+	embedded.Logger
+}
+
+func (l *logger) Emit(ctx context.Context, r log.Record) {
+	// TODO (#5061): Implement.
+}

sdk/log/processor.go

@@ -0,0 +1,44 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package log // import "go.opentelemetry.io/otel/sdk/log"
+
+import (
+	"context"
+)
+
+// Processor handles the processing of log records.
+//
+// Any of the Processor's methods may be called concurrently with itself
+// or with other methods. It is the responsibility of the Processor to manage
+// this concurrency.
+type Processor interface {
+	// OnEmit is called when a Record is emitted.
+	//
+	// Implementation should not interrupt the record processing
+	// if the context is canceled.
+	//
+	// All retry logic must be contained in this function. The SDK does not
+	// implement any retry logic. All errors returned by this function are
+	// considered unrecoverable and will be reported to a configured error
+	// Handler.
+	//
+	// Before modifying a Record, the implementation must use Record.Clone
+	// to create a copy that shares no state with the original.
+	OnEmit(ctx context.Context, record Record) error
+	// Shutdown is called when the SDK shuts down. Any cleanup or release of
+	// resources held by the exporter should be done in this call.
+	//
+	// The deadline or cancellation of the passed context must be honored. An
+	// appropriate error should be returned in these situations.
+	//
+	// After Shutdown is called, calls to Export, Shutdown, or ForceFlush
+	// should perform no operation and return nil error.
+	Shutdown(ctx context.Context) error
+	// ForceFlush exports log records to the configured Exporter that have not yet
+	// been exported.
+	//
+	// The deadline or cancellation of the passed context must be honored. An
+	// appropriate error should be returned in these situations.
+	ForceFlush(ctx context.Context) error
+}