From f907e77f9ce471564f4ed888d3688381492ed7af Mon Sep 17 00:00:00 2001
From: Austin Drenski <austin@austindrenski.io>
Date: Tue, 6 Feb 2024 16:29:22 -0500
Subject: [PATCH] Add experimental support for AddLinks()

This commit introduces a new ExperimentalSpan interface which aims to
allow the API and SDK to support experimental features in a way that
clearly communicates to users that they are opting into an API surface
that is still considered experimental by the spec and thus may break,
change, or be outright removed with minimal notice.

In the case of `AddLinks()`, users can explicitly type-check for the
new interface, making it obvious that they are interacting with an
API surface that is considered experimental:

```go
if s, ok := span.(trace.ExperimentalSpan); ok {
        s.AddLinks(links...)
}
```

See: #3919

Signed-off-by: Austin Drenski <austin@austindrenski.io>
---
 sdk/trace/experimental_span_test.go | 53 +++++++++++++++++++++++++++++
 sdk/trace/span.go                   | 10 ++++++
 trace/experimental.go               | 27 +++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 sdk/trace/experimental_span_test.go
 create mode 100644 trace/experimental.go

diff --git a/sdk/trace/experimental_span_test.go b/sdk/trace/experimental_span_test.go
new file mode 100644
index 00000000000..4c963b3f461
--- /dev/null
+++ b/sdk/trace/experimental_span_test.go
@@ -0,0 +1,53 @@
+// 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 trace
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/otel/trace"
+)
+
+func TestAddLinks(t *testing.T) {
+	ctx, tp := context.Background(), NewTracerProvider()
+	defer func(ctx context.Context, tp *TracerProvider) {
+		if err := tp.Shutdown(ctx); err != nil {
+			panic(err)
+		}
+	}(ctx, tp)
+
+	ctx, span := tp.Tracer("test").Start(ctx, "test_add_links")
+	defer span.End()
+
+	links := []trace.Link{
+		trace.LinkFromContext(ctx),
+	}
+
+	if s, ok := span.(trace.ExperimentalSpan); ok {
+		s.AddLinks(links...)
+	}
+
+	assert.Equal(t, len(links), len(span.(ReadOnlySpan).Links()))
+
+	for i, l := range span.(ReadOnlySpan).Links() {
+		assert.Equal(t, links[i], trace.Link{
+			Attributes:  l.Attributes,
+			SpanContext: l.SpanContext,
+		})
+	}
+}
diff --git a/sdk/trace/span.go b/sdk/trace/span.go
index 85bc702a019..f993f67deab 100644
--- a/sdk/trace/span.go
+++ b/sdk/trace/span.go
@@ -653,6 +653,16 @@ func (s *recordingSpan) Resource() *resource.Resource {
 	return s.tracer.provider.resource
 }
 
+func (s *recordingSpan) AddLinks(links ...trace.Link) {
+	if !s.IsRecording() {
+		return
+	}
+
+	for _, l := range links {
+		s.addLink(l)
+	}
+}
+
 func (s *recordingSpan) addLink(link trace.Link) {
 	if !s.IsRecording() || !link.SpanContext.IsValid() {
 		return
diff --git a/trace/experimental.go b/trace/experimental.go
new file mode 100644
index 00000000000..a327b5a76e2
--- /dev/null
+++ b/trace/experimental.go
@@ -0,0 +1,27 @@
+// 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 trace // import "go.opentelemetry.io/otel/trace"
+
+// ExperimentalSpan exposes the same methods as trace.Span and additionally supports
+// select features marked experimental by the specification and thus subject to breaking
+// changes without warning.
+//
+// Warning: methods may be added to or removed from this interface in minor releases.
+type ExperimentalSpan interface {
+	Span
+
+	// AddLinks adds links to the existing trace.Span after creation.
+	AddLinks(links ...Link)
+}