sdk/trace: self-observability: span metrics

CHANGELOG.md

@@ -42,6 +42,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add `ErrorType` attribute helper function to the `go.opentelmetry.io/otel/semconv/v1.34.0` package. (#6962)
 - Add `WithAllowKeyDuplication` in `go.opentelemetry.io/otel/sdk/log` which can be used to disable deduplication for log records. (#6968)
 - Add `Clone` method to `Record` in `go.opentelemetry.io/otel/log` that returns a copy of the record with no shared state. (#7001)
+- Add experimental self-observability span metrics in `go.opentelemetry.io/otel/sdk/trace`.
+  Check the `go.opentelemetry.io/otel/sdk/trace/internal/x` package documentation for more information. (#7027)
 
 ### Changed
 

exporters/otlp/otlplog/otlploggrpc/go.mod

@@ -50,3 +50,5 @@ replace go.opentelemetry.io/otel/trace => ../../../../trace
 replace go.opentelemetry.io/otel/metric => ../../../../metric
 
 replace go.opentelemetry.io/otel/sdk/log/logtest => ../../../../sdk/log/logtest
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../../sdk/metric

exporters/otlp/otlplog/otlploggrpc/go.sum

@@ -27,8 +27,6 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
 go.opentelemetry.io/proto/otlp v1.7.0 h1:jX1VolD6nHuFzOYso2E73H85i92Mv8JQYk0K9vz09os=
 go.opentelemetry.io/proto/otlp v1.7.0/go.mod h1:fSKjH6YJ7HDlwzltzyMj036AJ3ejJLCgCSHGj4efDDo=
 golang.org/x/net v0.42.0 h1:jzkYrhi3YQWD6MLBJcsklgQsoAcw89EcZbJw8Z614hs=

exporters/otlp/otlplog/otlploghttp/go.mod

@@ -50,3 +50,5 @@ replace go.opentelemetry.io/otel/sdk => ../../../../sdk
 replace go.opentelemetry.io/otel/metric => ../../../../metric
 
 replace go.opentelemetry.io/otel/log => ../../../../log
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../../sdk/metric

exporters/otlp/otlplog/otlploghttp/go.sum

@@ -27,8 +27,6 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
 go.opentelemetry.io/proto/otlp v1.7.0 h1:jX1VolD6nHuFzOYso2E73H85i92Mv8JQYk0K9vz09os=
 go.opentelemetry.io/proto/otlp v1.7.0/go.mod h1:fSKjH6YJ7HDlwzltzyMj036AJ3ejJLCgCSHGj4efDDo=
 golang.org/x/net v0.42.0 h1:jzkYrhi3YQWD6MLBJcsklgQsoAcw89EcZbJw8Z614hs=

exporters/otlp/otlptrace/go.mod

@@ -31,3 +31,5 @@ replace go.opentelemetry.io/otel/sdk => ../../../sdk
 replace go.opentelemetry.io/otel/trace => ../../../trace
 
 replace go.opentelemetry.io/otel/metric => ../../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric

exporters/otlp/otlptrace/otlptracegrpc/go.mod

@@ -41,3 +41,5 @@ replace go.opentelemetry.io/otel/exporters/otlp/otlptrace => ../
 replace go.opentelemetry.io/otel/trace => ../../../../trace
 
 replace go.opentelemetry.io/otel/metric => ../../../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../../sdk/metric

exporters/otlp/otlptrace/otlptracegrpc/go.sum

@@ -27,8 +27,6 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
 go.opentelemetry.io/proto/otlp v1.7.0 h1:jX1VolD6nHuFzOYso2E73H85i92Mv8JQYk0K9vz09os=
 go.opentelemetry.io/proto/otlp v1.7.0/go.mod h1:fSKjH6YJ7HDlwzltzyMj036AJ3ejJLCgCSHGj4efDDo=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=

exporters/otlp/otlptrace/otlptracehttp/go.mod

@@ -40,3 +40,5 @@ replace go.opentelemetry.io/otel/sdk => ../../../../sdk
 replace go.opentelemetry.io/otel/trace => ../../../../trace
 
 replace go.opentelemetry.io/otel/metric => ../../../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../../sdk/metric

exporters/otlp/otlptrace/otlptracehttp/go.sum

@@ -27,8 +27,6 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
 go.opentelemetry.io/proto/otlp v1.7.0 h1:jX1VolD6nHuFzOYso2E73H85i92Mv8JQYk0K9vz09os=
 go.opentelemetry.io/proto/otlp v1.7.0/go.mod h1:fSKjH6YJ7HDlwzltzyMj036AJ3ejJLCgCSHGj4efDDo=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=

exporters/stdout/stdoutlog/go.mod

@@ -40,3 +40,5 @@ replace go.opentelemetry.io/otel/trace => ../../../trace
 replace go.opentelemetry.io/otel/sdk => ../../../sdk
 
 replace go.opentelemetry.io/otel/metric => ../../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric

exporters/stdout/stdouttrace/go.mod

@@ -29,3 +29,5 @@ require (
 replace go.opentelemetry.io/otel/trace => ../../../trace
 
 replace go.opentelemetry.io/otel/metric => ../../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../../sdk/metric

exporters/zipkin/go.mod

@@ -30,3 +30,5 @@ replace go.opentelemetry.io/otel => ../..
 replace go.opentelemetry.io/otel/sdk => ../../sdk
 
 replace go.opentelemetry.io/otel/metric => ../../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../sdk/metric

sdk/go.mod

@@ -10,6 +10,8 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/stretchr/testify v1.10.0
 	go.opentelemetry.io/otel v1.37.0
+	go.opentelemetry.io/otel/metric v1.37.0
+	go.opentelemetry.io/otel/sdk/metric v1.37.0
 	go.opentelemetry.io/otel/trace v1.37.0
 	go.uber.org/goleak v1.3.0
 	golang.org/x/sys v0.34.0
@@ -20,10 +22,11 @@ require (
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
-	go.opentelemetry.io/otel/metric v1.37.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 
 replace go.opentelemetry.io/otel/trace => ../trace
 
 replace go.opentelemetry.io/otel/metric => ../metric
+
+replace go.opentelemetry.io/otel/sdk/metric => ./metric

sdk/log/go.mod

@@ -32,3 +32,5 @@ replace go.opentelemetry.io/otel/sdk => ../
 replace go.opentelemetry.io/otel/log => ../../log
 
 replace go.opentelemetry.io/otel => ../..
+
+replace go.opentelemetry.io/otel/sdk/metric => ../metric

sdk/log/logtest/go.mod

@@ -34,3 +34,5 @@ replace go.opentelemetry.io/otel/sdk/log => ../
 replace go.opentelemetry.io/otel/log => ../../../log
 
 replace go.opentelemetry.io/otel => ../../..
+
+replace go.opentelemetry.io/otel/sdk/metric => ../../metric

sdk/trace/doc.go

@@ -6,5 +6,8 @@ Package trace contains support for OpenTelemetry distributed tracing.
 
 The following assumes a basic familiarity with OpenTelemetry concepts.
 See https://opentelemetry.io.
+
+See [go.opentelemetry.io/otel/sdk/trace/internal/x] for information about
+the experimental features.
 */
 package trace // import "go.opentelemetry.io/otel/sdk/trace"

sdk/trace/internal/x/doc.go

@@ -0,0 +1,32 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package x documents experimental features for [go.opentelemetry.io/otel/sdk/trace].
+
+# Compatibility and Stability
+
+Experimental features do not fall within the scope of the [OpenTelemetry Go versioning and stability policy].
+These features may change in backwards incompatible ways as feedback is applied.
+These features may be removed or modified in successive version releases, including patch versions.
+
+When an experimental feature is promoted to a stable feature, a migration path will be included in the changelog entry of the release.
+There is no guarantee that any environment variable feature flags that enabled the experimental feature will be supported by the stable version.
+If they are supported, they may be accompanied with a deprecation notice stating a timeline for the removal of that support.
+
+# Self-Observability
+
+The SDK provides a self-observability feature that allows you to monitor the SDK itself.
+
+To opt-in, set the environment variable OTEL_GO_X_SELF_OBSERVABILITY to "true".
+
+When enabled, the SDK will create following metrics using the global MeterProvider:
+  - otel.sdk.span.live
+  - otel.sdk.span.started
+
+Please see the [Semantic conventions for OpenTelemetry SDK metrics] documentation for more details on these metrics.
+
+[OpenTelemetry Go versioning and stability policy]: https://github.com/open-telemetry/opentelemetry-go/blob/main/VERSIONING.md
+[Semantic conventions for OpenTelemetry SDK metrics]: https://github.com/open-telemetry/semantic-conventions/blob/v1.36.0/docs/otel/sdk-metrics.md
+*/
+package x // import "go.opentelemetry.io/otel/sdk/trace/internal/x"

sdk/trace/provider.go

@@ -6,6 +6,8 @@ package trace // import "go.opentelemetry.io/otel/sdk/trace"
 import (
 	"context"
 	"fmt"
+	"os"
+	"strings"
 	"sync"
 	"sync/atomic"
 
@@ -159,6 +161,10 @@ func (p *TracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.T
 				provider:             p,
 				instrumentationScope: is,
 			}
+			env := os.Getenv("OTEL_GO_X_SELF_OBSERVABILITY")
+			if strings.ToLower(env) == "true" {
+				t.initSelfObservability(otel.GetMeterProvider())
+			}
 			p.namedTracer[is] = t
 		}
 		return t, ok

sdk/trace/span.go

@@ -21,6 +21,7 @@ import (
 	"go.opentelemetry.io/otel/sdk/instrumentation"
 	"go.opentelemetry.io/otel/sdk/resource"
 	semconv "go.opentelemetry.io/otel/semconv/v1.34.0"
+	"go.opentelemetry.io/otel/semconv/v1.34.0/otelconv"
 	"go.opentelemetry.io/otel/trace"
 	"go.opentelemetry.io/otel/trace/embedded"
 )
@@ -496,6 +497,20 @@ func (s *recordingSpan) End(options ...trace.SpanEndOption) {
 	}
 	s.mu.Unlock()
 
+	defer func() {
+		if s.tracer.selfObservabilityEnabled {
+			var samplingResultAttr attribute.KeyValue
+			if s.spanContext.IsSampled() {
+				samplingResultAttr = otelconv.SDKSpanEnded{}.AttrSpanSamplingResult(
+					otelconv.SpanSamplingResultRecordAndSample,
+				)
+			} else {
+				samplingResultAttr = otelconv.SDKSpanEnded{}.AttrSpanSamplingResult(otelconv.SpanSamplingResultRecordOnly)
+			}
+			s.tracer.spanLiveMetric.Add(context.Background(), -1, samplingResultAttr)
+		}
+	}()
+
 	sps := s.tracer.provider.getSpanProcessors()
 	if len(sps) == 0 {
 		return

sdk/trace/trace_test.go

@@ -22,9 +22,14 @@ import (
 	"go.opentelemetry.io/otel"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/sdk"
 	"go.opentelemetry.io/otel/sdk/instrumentation"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/metric/metricdata"
+	"go.opentelemetry.io/otel/sdk/metric/metricdata/metricdatatest"
 	"go.opentelemetry.io/otel/sdk/resource"
 	semconv "go.opentelemetry.io/otel/semconv/v1.34.0"
+	"go.opentelemetry.io/otel/semconv/v1.34.0/otelconv"
 	"go.opentelemetry.io/otel/trace"
 )
 
@@ -2177,6 +2182,124 @@ func TestAddLinkToNonRecordingSpan(t *testing.T) {
 	}
 }
 
+func TestSelfObservabilty(t *testing.T) {
+	var got metricdata.ResourceMetrics
+
+	t.Setenv("OTEL_GO_X_SELF_OBSERVABILITY", "True")
+	prev := otel.GetMeterProvider()
+	defer otel.SetMeterProvider(prev)
+	r := metric.NewManualReader()
+	mp := metric.NewMeterProvider(metric.WithReader(r))
+	otel.SetMeterProvider(mp)
+
+	tp := NewTracerProvider()
+	_, span := tp.Tracer("").Start(context.Background(), "StartSpan")
+
+	want := metricdata.ScopeMetrics{
+		Scope: instrumentation.Scope{
+			Name:      "go.opentelemetry.io/otel/sdk/trace",
+			Version:   sdk.Version(),
+			SchemaURL: semconv.SchemaURL,
+		},
+		Metrics: []metricdata.Metrics{
+			{
+				Name:        otelconv.SDKSpanLive{}.Name(),
+				Description: otelconv.SDKSpanLive{}.Description(),
+				Unit:        otelconv.SDKSpanLive{}.Unit(),
+				Data: metricdata.Sum[int64]{
+					Temporality: metricdata.CumulativeTemporality,
+					DataPoints: []metricdata.DataPoint[int64]{
+						{
+							Attributes: attribute.NewSet(
+								otelconv.SDKSpanLive{}.AttrSpanSamplingResult(
+									otelconv.SpanSamplingResultRecordAndSample,
+								),
+							),
+							Value: 1,
+						},
+					},
+				},
+			},
+			{
+				Name:        otelconv.SDKSpanEnded{}.Name(),
+				Description: otelconv.SDKSpanEnded{}.Description(),
+				Unit:        otelconv.SDKSpanEnded{}.Unit(),
+				Data: metricdata.Sum[int64]{
+					Temporality: metricdata.CumulativeTemporality,
+					IsMonotonic: true,
+					DataPoints: []metricdata.DataPoint[int64]{
+						{
+							Attributes: attribute.NewSet(
+								otelconv.SDKSpanEnded{}.AttrSpanSamplingResult(
+									otelconv.SpanSamplingResultRecordAndSample,
+								),
+							),
+							Value: 1,
+						},
+					},
+				},
+			},
+		},
+	}
+	err := r.Collect(context.Background(), &got)
+	require.NoError(t, err)
+	require.Len(t, got.ScopeMetrics, 1)
+	metricdatatest.AssertEqual(t, want, got.ScopeMetrics[0], metricdatatest.IgnoreTimestamp())
+
+	span.End()
+
+	want = metricdata.ScopeMetrics{
+		Scope: instrumentation.Scope{
+			Name:      "go.opentelemetry.io/otel/sdk/trace",
+			Version:   sdk.Version(),
+			SchemaURL: semconv.SchemaURL,
+		},
+		Metrics: []metricdata.Metrics{
+			{
+				Name:        otelconv.SDKSpanLive{}.Name(),
+				Description: otelconv.SDKSpanLive{}.Description(),
+				Unit:        otelconv.SDKSpanLive{}.Unit(),
+				Data: metricdata.Sum[int64]{
+					Temporality: metricdata.CumulativeTemporality,
+					DataPoints: []metricdata.DataPoint[int64]{
+						{
+							Attributes: attribute.NewSet(
+								otelconv.SDKSpanLive{}.AttrSpanSamplingResult(
+									otelconv.SpanSamplingResultRecordAndSample,
+								),
+							),
+							Value: 0, // No live spans at this point.
+						},
+					},
+				},
+			},
+			{
+				Name:        otelconv.SDKSpanEnded{}.Name(),
+				Description: otelconv.SDKSpanEnded{}.Description(),
+				Unit:        otelconv.SDKSpanEnded{}.Unit(),
+				Data: metricdata.Sum[int64]{
+					Temporality: metricdata.CumulativeTemporality,
+					IsMonotonic: true,
+					DataPoints: []metricdata.DataPoint[int64]{
+						{
+							Attributes: attribute.NewSet(
+								otelconv.SDKSpanEnded{}.AttrSpanSamplingResult(
+									otelconv.SpanSamplingResultRecordAndSample,
+								),
+							),
+							Value: 1,
+						},
+					},
+				},
+			},
+		},
+	}
+	err = r.Collect(context.Background(), &got)
+	require.NoError(t, err)
+	require.Len(t, got.ScopeMetrics, 1)
+	metricdatatest.AssertEqual(t, want, got.ScopeMetrics[0], metricdatatest.IgnoreTimestamp())
+}
+
 func BenchmarkTraceStart(b *testing.B) {
 	tracer := NewTracerProvider().Tracer("")
 	ctx := trace.ContextWithSpanContext(context.Background(), trace.SpanContext{})