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: open-telemetry#3919

Signed-off-by: Austin Drenski <austin@austindrenski.io>

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,
+		})
+	}
+}

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

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)
+}