[WIP] Add schema URL support to Tracer

[Do not merge, this is a draft to get maintainers' feedback]

This adds support for schema URL according to the specification:
open-telemetry/opentelemetry-specification#1666
(Link to replaced by the link to the spec after that PR is merged)

TODO:

Populate the schema_url field in the OTLP after this PR
open-telemetry/opentelemetry-proto#298
is merged and the field is available in the proto message.

This is the first in the series of changes that are necessary to add
support for schemas in Go SDK. Subsequent PRs will add support in Meter
and Resource. We will also see if we can find a good way to group
semantic conventions with the schema version that declares them.

CHANGELOG.md

@@ -26,6 +26,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   This type can be used as a testing replacement for the `SpanSnapshot` that was removed from the `go.opentelemetry.io/otel/sdk/trace` package. (#1873)
 - Adds support for scheme in `OTEL_EXPORTER_OTLP_ENDPOINT` according to the spec. (#1886)
 - An example of using OpenTelemetry Go as a trace context forwarder. (#1912)
+- Adds `trace.WithSchemaURL` option for configuring the tracer with a Schema URL. (#1889)
 
 ### Changed
 

exporters/otlp/internal/transform/span.go

@@ -61,6 +61,8 @@ func Spans(sdl []tracesdk.ReadOnlySpan) []*tracepb.ResourceSpans {
 				InstrumentationLibrary: instrumentationLibrary(sd.InstrumentationLibrary()),
 				Spans:                  []*tracepb.Span{},
 			}
+			// TODO: set schema_url field of ils when it is available in the proto.
+			_ = sd.InstrumentationLibrary().SchemaURL
 		}
 		ils.Spans = append(ils.Spans, span(sd))
 		ilsm[iKey] = ils

exporters/otlp/internal/transform/span_test.go

@@ -262,8 +262,9 @@ func TestSpanData(t *testing.T) {
 		DroppedLinks:      3,
 		Resource:          resource.NewWithAttributes(attribute.String("rk1", "rv1"), attribute.Int64("rk2", 5)),
 		InstrumentationLibrary: instrumentation.Library{
-			Name:    "go.opentelemetry.io/test/otel",
-			Version: "v0.0.1",
+			Name:      "go.opentelemetry.io/test/otel",
+			Version:   "v0.0.1",
+			SchemaURL: "https://opentelemetry.io/schemas/1.2.0",
 		},
 	}
 
@@ -294,6 +295,7 @@ func TestSpanData(t *testing.T) {
 	assert.Equal(t, got[0].GetResource(), Resource(spanData.Resource))
 	ilSpans := got[0].GetInstrumentationLibrarySpans()
 	require.Len(t, ilSpans, 1)
+	// TODO: Add SchemaURL field checking once the field is added to the proto.
 	assert.Equal(t, ilSpans[0].GetInstrumentationLibrary(), instrumentationLibrary(spanData.InstrumentationLibrary))
 	require.Len(t, ilSpans[0].Spans, 1)
 	actualSpan := ilSpans[0].Spans[0]

exporters/stdout/example_test.go

@@ -35,6 +35,7 @@ var (
 	tracer = otel.GetTracerProvider().Tracer(
 		instrumentationName,
 		trace.WithInstrumentationVersion(instrumentationVersion),
+		trace.WithSchemaURL("https://opentelemetry.io/schemas/1.2.0"),
 	)
 
 	meter = global.GetMeterProvider().Meter(

exporters/stdout/trace_test.go

@@ -177,7 +177,8 @@ func TestExporter_ExportSpan(t *testing.T) {
 		],
 		"InstrumentationLibrary": {
 			"Name": "",
-			"Version": ""
+			"Version": "",
+			"SchemaURL": ""
 		}
 	}
 ]

sdk/instrumentation/library.go

@@ -32,4 +32,6 @@ type Library struct {
 	Name string
 	// Version is the version of the instrumentation library.
 	Version string
+	// SchemaURL of the telemetry emitted by the library.
+	SchemaURL string
 }

sdk/trace/provider.go

@@ -115,8 +115,9 @@ func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.T
 		name = defaultTracerName
 	}
 	il := instrumentation.Library{
-		Name:    name,
-		Version: c.InstrumentationVersion,
+		Name:      name,
+		Version:   c.InstrumentationVersion,
+		SchemaURL: c.SchemaURL,
 	}
 	t, ok := p.namedTracer[il]
 	if !ok {

sdk/trace/provider_test.go

@@ -20,6 +20,8 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+
+	"go.opentelemetry.io/otel/trace"
 )
 
 type basicSpanProcesor struct {
@@ -82,3 +84,13 @@ func TestFailedProcessorShutdownInUnregister(t *testing.T) {
 	err := stp.Shutdown(context.Background())
 	assert.NoError(t, err)
 }
+
+func TestSchemaURL(t *testing.T) {
+	stp := NewTracerProvider()
+	schemaURL := "https://opentelemetry.io/schemas/1.2.0"
+	tracerIface := stp.Tracer("tracername", trace.WithSchemaURL(schemaURL))
+
+	// Verify that the SchemaURL of the constructed Tracer is correctly populated.
+	tracerStruct := tracerIface.(*tracer)
+	assert.EqualValues(t, schemaURL, tracerStruct.instrumentationLibrary.SchemaURL)
+}

sdk/trace/trace_test.go

@@ -1284,7 +1284,7 @@ func TestWithResource(t *testing.T) {
 	}
 }
 
-func TestWithInstrumentationVersion(t *testing.T) {
+func TestWithInstrumentationVersionAndSchema(t *testing.T) {
 	te := NewTestExporter()
 	tp := NewTracerProvider(WithSyncer(te), WithResource(resource.Empty()))
 
@@ -1293,6 +1293,7 @@ func TestWithInstrumentationVersion(t *testing.T) {
 	_, span := tp.Tracer(
 		"WithInstrumentationVersion",
 		trace.WithInstrumentationVersion("v0.1.0"),
+		trace.WithSchemaURL("https://opentelemetry.io/schemas/1.2.0"),
 	).Start(ctx, "span0")
 	got, err := endSpan(te, span)
 	if err != nil {
@@ -1308,8 +1309,9 @@ func TestWithInstrumentationVersion(t *testing.T) {
 		name:     "span0",
 		spanKind: trace.SpanKindInternal,
 		instrumentationLibrary: instrumentation.Library{
-			Name:    "WithInstrumentationVersion",
-			Version: "v0.1.0",
+			Name:      "WithInstrumentationVersion",
+			Version:   "v0.1.0",
+			SchemaURL: "https://opentelemetry.io/schemas/1.2.0",
 		},
 	}
 	if diff := cmpDiff(got, want); diff != "" {

trace/config.go

@@ -25,6 +25,8 @@ type TracerConfig struct {
 	// InstrumentationVersion is the version of the library providing
 	// instrumentation.
 	InstrumentationVersion string
+	// SchemaURL of the telemetry emitted by the Tracer.
+	SchemaURL string
 }
 
 // NewTracerConfig applies all the options to a returned TracerConfig.
@@ -203,3 +205,16 @@ func (i instrumentationVersionOption) ApplyTracer(config *TracerConfig) {
 }
 
 func (instrumentationVersionOption) private() {}
+
+// WithSchemaURL sets the schema URL for the Tracer.
+func WithSchemaURL(schemaURL string) InstrumentationOption {
+	return schemaURLOption(schemaURL)
+}
+
+type schemaURLOption string
+
+func (i schemaURLOption) ApplyTracer(config *TracerConfig) {
+	config.SchemaURL = string(i)
+}
+
+func (schemaURLOption) private() {}

trace/config_test.go

@@ -177,6 +177,7 @@ func TestNewSpanConfig(t *testing.T) {
 func TestTracerConfig(t *testing.T) {
 	v1 := "semver:0.0.1"
 	v2 := "semver:1.0.0"
+	schemaURL := "https://opentelemetry.io/schemas/1.2.0"
 	tests := []struct {
 		options  []TracerOption
 		expected *TracerConfig
@@ -204,6 +205,14 @@ func TestTracerConfig(t *testing.T) {
 				InstrumentationVersion: v2,
 			},
 		},
+		{
+			[]TracerOption{
+				WithSchemaURL(schemaURL),
+			},
+			&TracerConfig{
+				SchemaURL: schemaURL,
+			},
+		},
 	}
 	for _, test := range tests {
 		config := NewTracerConfig(test.options...)