Add initial Logs Bridge API scaffolding (open-telemetry#4907)

* Add go.mod

* Exclude otel/log in versions.yaml

* Add package documentation stub

* Update dependabot config

* Add initial log API scaffolding

Author: MrAlias

.github/dependabot.yml

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

log/doc.go

@@ -0,0 +1,21 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package log provides the OpenTelemetry Logs Bridge API.
+*/
+
+// TODO (#4908): expand documentation stub.
+
+package log // import "go.opentelemetry.io/otel/log"

log/go.mod

@@ -0,0 +1,11 @@
+module go.opentelemetry.io/otel/log
+
+go 1.20
+
+require go.opentelemetry.io/otel v1.23.1
+
+replace go.opentelemetry.io/otel/metric => ../metric
+
+replace go.opentelemetry.io/otel => ../
+
+replace go.opentelemetry.io/otel/trace => ../trace

log/go.sum

@@ -0,0 +1,5 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

log/keyvalue.go

@@ -0,0 +1,132 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:generate stringer -type=Kind -trimprefix=Kind
+
+package log // import "go.opentelemetry.io/otel/log"
+
+// Kind is the kind of a [Value].
+type Kind int
+
+// Kind values.
+const (
+	KindEmpty Kind = iota
+	KindBool
+	KindFloat64
+	KindInt64
+	KindString
+	KindBytes
+	KindList
+	KindMap
+)
+
+// A Value represents a structured log value.
+type Value struct{} // TODO (#4914): implement.
+
+// StringValue returns a new [Value] for a string.
+func StringValue(v string) Value { return Value{} } // TODO (#4914): implement.
+
+// IntValue returns a [Value] for an int.
+func IntValue(v int) Value { return Value{} } // TODO (#4914): implement.
+
+// Int64Value returns a [Value] for an int64.
+func Int64Value(v int64) Value { return Value{} } // TODO (#4914): implement.
+
+// Float64Value returns a [Value] for a float64.
+func Float64Value(v float64) Value { return Value{} } // TODO (#4914): implement.
+
+// BoolValue returns a [Value] for a bool.
+func BoolValue(v bool) Value { //nolint:revive // Not a control flag.
+	// TODO (#4914): implement.
+	return Value{}
+}
+
+// BytesValue returns a [Value] for a byte slice. The passed slice must not be
+// changed after it is passed.
+func BytesValue(v []byte) Value { return Value{} } // TODO (#4914): implement.
+
+// ListValue returns a [Value] for a slice of [Value]. The passed slice must
+// not be changed after it is passed.
+func ListValue(vs ...Value) Value { return Value{} } // TODO (#4914): implement.
+
+// MapValue returns a new [Value] for a slice of key-value pairs. The passed
+// slice must not be changed after it is passed.
+func MapValue(kvs ...KeyValue) Value { return Value{} } // TODO (#4914): implement.
+
+// AsAny returns the value held by v as an any.
+func (v Value) AsAny() any { return nil } // TODO (#4914): implement
+
+// AsString returns the value held by v as a string.
+func (v Value) AsString() string { return "" } // TODO (#4914): implement
+
+// AsInt64 returns the value held by v as an int64.
+func (v Value) AsInt64() int64 { return 0 } // TODO (#4914): implement
+
+// AsBool returns the value held by v as a bool.
+func (v Value) AsBool() bool { return false } // TODO (#4914): implement
+
+// AsFloat64 returns the value held by v as a float64.
+func (v Value) AsFloat64() float64 { return 0 } // TODO (#4914): implement
+
+// AsBytes returns the value held by v as a []byte.
+func (v Value) AsBytes() []byte { return nil } // TODO (#4914): implement
+
+// AsList returns the value held by v as a []Value.
+func (v Value) AsList() []Value { return nil } // TODO (#4914): implement
+
+// AsMap returns the value held by v as a []KeyValue.
+func (v Value) AsMap() []KeyValue { return nil } // TODO (#4914): implement
+
+// Kind returns the Kind of v.
+func (v Value) Kind() Kind { return KindEmpty } // TODO (#4914): implement.
+
+// Empty returns if v does not hold any value.
+func (v Value) Empty() bool { return false } // TODO (#4914): implement
+
+// Equal returns if v is equal to w.
+func (v Value) Equal(w Value) bool { return false } // TODO (#4914): implement
+
+// An KeyValue is a key-value pair used to represent a log attribute (a
+// superset of [go.opentelemetry.io/otel/attribute.KeyValue]) and map item.
+type KeyValue struct {
+	Key   string
+	Value Value
+}
+
+// Equal returns if a is equal to b.
+func (a KeyValue) Equal(b KeyValue) bool { return false } // TODO (#4914): implement
+
+// String returns an KeyValue for a string value.
+func String(key, value string) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Int64 returns an KeyValue for an int64 value.
+func Int64(key string, value int64) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Int returns an KeyValue for an int value.
+func Int(key string, value int) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Float64 returns an KeyValue for a float64 value.
+func Float64(key string, v float64) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Bool returns an KeyValue for a bool value.
+func Bool(key string, v bool) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Bytes returns an KeyValue for a []byte value.
+func Bytes(key string, v []byte) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// List returns an KeyValue for a []Value value.
+func List(key string, args ...Value) KeyValue { return KeyValue{} } // TODO (#4914): implement
+
+// Map returns an KeyValue for a map value.
+func Map(key string, args ...KeyValue) KeyValue { return KeyValue{} } // TODO (#4914): implement

log/kind_string.go

@@ -0,0 +1,65 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package log // import "go.opentelemetry.io/otel/log"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel/attribute"
+)
+
+// Logger emits log records.
+//
+// Warning: Methods may be added to this interface in minor releases. See
+// package documentation on API implementation for information on how to set
+// default behavior for unimplemented methods.
+type Logger interface {
+	// TODO (#4909): embed an embedded type from otel/log/embedded.
+
+	// Emit emits a log record.
+	//
+	// The record may be held by the implementation. Callers should not mutate
+	// the record after passed.
+	//
+	// Implementations of this method need to be safe for a user to call
+	// concurrently.
+	Emit(ctx context.Context, record Record)
+}
+
+// LoggerOption applies configuration options to a [Logger].
+type LoggerOption interface {
+	// applyLogger is used to set a LoggerOption value of a LoggerConfig.
+	applyLogger(LoggerConfig) LoggerConfig
+}
+
+// LoggerConfig contains options for a [Logger].
+type LoggerConfig struct {
+	// Ensure forward compatibility by explicitly making this not comparable.
+	noCmp [0]func() //nolint: unused  // This is indeed used.
+}
+
+// NewLoggerConfig returns a new [LoggerConfig] with all the opts applied.
+func NewLoggerConfig(opts ...LoggerOption) LoggerConfig { return LoggerConfig{} } // TODO (#4911): implement.
+
+// InstrumentationVersion returns the version of the library providing
+// instrumentation.
+func (cfg LoggerConfig) InstrumentationVersion() string { return "" } // TODO (#4911): implement.
+
+// InstrumentationAttributes returns the attributes associated with the library
+// providing instrumentation.
+func (cfg LoggerConfig) InstrumentationAttributes() attribute.Set { return attribute.NewSet() } // TODO (#4911): implement.
+
+// SchemaURL returns the schema URL of the library providing instrumentation.
+func (cfg LoggerConfig) SchemaURL() string { return "" } // TODO (#4911): implement.

log/logger.go

@@ -0,0 +1,32 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package log // import "go.opentelemetry.io/otel/log"
+
+// LoggerProvider provides access to [Logger].
+//
+// Warning: Methods may be added to this interface in minor releases. See
+// package documentation on API implementation for information on how to set
+// default behavior for unimplemented methods.
+type LoggerProvider interface {
+	// TODO (#4909): embed an embedded type from otel/log/embedded.
+
+	// Logger returns a new [Logger] with the provided name and configuration.
+	//
+	// If name is empty, implementations need to provide a default name.
+	//
+	// Implementations of this method need to be safe for a user to call
+	// concurrently.
+	Logger(name string, options ...LoggerOption) Logger
+}

log/provider.go

@@ -0,0 +1,62 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package log // import "go.opentelemetry.io/otel/log"
+
+import "time"
+
+// Record represents a log record.
+type Record struct{} // TODO (#4913): implement.
+
+// Timestamp returns the time when the log record occurred.
+func (r *Record) Timestamp() time.Time { return time.Time{} } // TODO (#4913): implement.
+
+// SetTimestamp sets the time when the log record occurred.
+func (r *Record) SetTimestamp(t time.Time) {} // TODO (#4913): implement.
+
+// ObservedTimestamp returns the time when the log record was observed.
+func (r *Record) ObservedTimestamp() time.Time { return time.Time{} } // TODO (#4913): implement.
+
+// SetObservedTimestamp sets the time when the log record was observed.
+func (r *Record) SetObservedTimestamp(t time.Time) {} // TODO (#4913): implement.
+
+// Severity returns the [Severity] of the log record.
+func (r *Record) Severity() Severity { return 0 } // TODO (#4913): implement.
+
+// SetSeverity sets the [Severity] level of the log record.
+func (r *Record) SetSeverity(level Severity) {} // TODO (#4913): implement.
+
+// SeverityText returns severity (also known as log level) text. This is the
+// original string representation of the severity as it is known at the source.
+func (r *Record) SeverityText() string { return "" } // TODO (#4913): implement.
+
+// SetSeverityText sets severity (also known as log level) text. This is the
+// original string representation of the severity as it is known at the source.
+func (r *Record) SetSeverityText(text string) {} // TODO (#4913): implement.
+
+// Body returns the body of the log record.
+func (r *Record) Body() Value { return Value{} } // TODO (#4913): implement.
+
+// SetBody sets the body of the log record.
+func (r *Record) SetBody(v Value) {} // TODO (#4913): implement.
+
+// WalkAttributes walks all attributes the log record holds by calling f for
+// each on each [KeyValue] in the [Record]. Iteration stops if f returns false.
+func (r *Record) WalkAttributes(f func(KeyValue) bool) {} // TODO (#4913): implement.
+
+// AddAttributes adds attributes to the log record.
+func (r *Record) AddAttributes(attributes ...KeyValue) {} // TODO (#4913): implement.
+
+// AttributesLen returns the number of attributes in the log record.
+func (r *Record) AttributesLen() int { return 0 } // TODO (#4913): implement.