Merge branch 'main' into use-semconv-1.23.1

CHANGELOG.md

@@ -19,6 +19,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - The `go.opentelemetry.io/otel/semconv/v1.24.0` package.
   The package contains semantic conventions from the `v1.24.0` version of the OpenTelemetry Semantic Conventions. (#4770)
 - Add `WithResourceAsConstantLabels` option to apply resource attributes for every metric emitted by the Prometheus exporter. (#4733)
+- Experimental cardinality limiting is added to the metric SDK.
+  See [metric documentation](./sdk/metric/EXPERIMENTAL.md#cardinality-limit) for more information about this feature and how to enable it. (#4457)
 
 ### Changed
 
@@ -33,6 +35,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Fixed
 
 - Fix `Parse` in `go.opentelemetry.io/otel/baggage` to validate member value before percent-decoding. (#4755)
+- Fix whitespace encoding of `Member.String` in `go.opentelemetry.io/otel/baggage`. (#4756)
 
 ## [1.21.0/0.44.0] 2023-11-16
 

baggage/baggage.go

@@ -320,8 +320,10 @@ func (m Member) Properties() []Property { return m.properties.Copy() }
 // String encodes Member into a string compliant with the W3C Baggage
 // specification.
 func (m Member) String() string {
-	// A key is just an ASCII string, but a value is URL encoded UTF-8.
-	s := fmt.Sprintf("%s%s%s", m.key, keyValueDelimiter, url.QueryEscape(m.value))
+	// A key is just an ASCII string. A value is restricted to be
+	// US-ASCII characters excluding CTLs, whitespace,
+	// DQUOTE, comma, semicolon, and backslash.
+	s := fmt.Sprintf("%s%s%s", m.key, keyValueDelimiter, url.PathEscape(m.value))
 	if len(m.properties) > 0 {
 		s = fmt.Sprintf("%s%s%s", s, propertyDelimiter, m.properties.String())
 	}

baggage/baggage_test.go

@@ -382,6 +382,13 @@ func TestBaggageParse(t *testing.T) {
 				"foo": {Value: "2"},
 			},
 		},
+		{
+			name: "= value",
+			in:   "key==",
+			want: baggage.List{
+				"key": {Value: "="},
+			},
+		},
 		{
 			name: "url encoded value",
 			in:   "key1=val%252%2C",
@@ -486,19 +493,46 @@ func TestBaggageString(t *testing.T) {
 			},
 		},
 		{
-			name: "URL encoded value",
-			out:  "foo=1%3D1",
+			name: "Encoded value",
+			// Allowed value characters are:
+			//
+			//   %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+			//
+			// Meaning, US-ASCII characters excluding CTLs, whitespace,
+			// DQUOTE, comma, semicolon, and backslash. All excluded
+			// characters need to be percent encoded.
+			//
+			// Ideally, the want result is:
+			// out: "foo=%00%01%02%03%04%05%06%07%08%09%0A%0B%0C%0D%0E%0F%10%11%12%13%14%15%16%17%18%19%1A%1B%1C%1D%1E%1F%20!%22#$%25&'()*+%2C-./0123456789:%3B<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[%5C]^_%60abcdefghijklmnopqrstuvwxyz{|}~%7F",
+			// However, the following characters are escaped:
+			// !#'()*/<>?[]^{|}
+			// It is not necessary, but still provides a correct result.
+			out: "foo=%00%01%02%03%04%05%06%07%08%09%0A%0B%0C%0D%0E%0F%10%11%12%13%14%15%16%17%18%19%1A%1B%1C%1D%1E%1F%20%21%22%23$%25&%27%28%29%2A+%2C-.%2F0123456789:%3B%3C=%3E%3F@ABCDEFGHIJKLMNOPQRSTUVWXYZ%5B%5C%5D%5E_%60abcdefghijklmnopqrstuvwxyz%7B%7C%7D~%7F",
 			baggage: baggage.List{
-				"foo": {Value: "1=1"},
+				"foo": {Value: func() string {
+					// All US-ASCII characters.
+					b := [128]byte{}
+					for i := range b {
+						b[i] = byte(i)
+					}
+					return string(b[:])
+				}()},
 			},
 		},
 		{
 			name: "plus",
-			out:  "foo=1%2B1",
+			out:  "foo=1+1",
 			baggage: baggage.List{
 				"foo": {Value: "1+1"},
 			},
 		},
+		{
+			name: "equal",
+			out:  "foo=1=1",
+			baggage: baggage.List{
+				"foo": {Value: "1=1"},
+			},
+		},
 		{
 			name: "single member empty value with properties",
 			out:  "foo=;red;state=on",
@@ -561,8 +595,10 @@ func TestBaggageString(t *testing.T) {
 	}
 
 	for _, tc := range testcases {
-		b := Baggage{tc.baggage}
-		assert.Equal(t, tc.out, orderer(b.String()))
+		t.Run(tc.name, func(t *testing.T) {
+			b := Baggage{tc.baggage}
+			assert.Equal(t, tc.out, orderer(b.String()))
+		})
 	}
 }
 
@@ -863,9 +899,9 @@ func TestMemberString(t *testing.T) {
 	memberStr := member.String()
 	assert.Equal(t, memberStr, "key=value")
 	// encoded key
-	member, _ = NewMember("key", "%3B")
+	member, _ = NewMember("key", "%3B%20")
 	memberStr = member.String()
-	assert.Equal(t, memberStr, "key=%3B")
+	assert.Equal(t, memberStr, "key=%3B%20")
 }
 
 var benchBaggage Baggage

propagation/baggage_test.go

@@ -214,9 +214,9 @@ func TestInjectBaggageToHTTPReq(t *testing.T) {
 		{
 			name: "values with escaped chars",
 			mems: members{
-				{Key: "key2", Value: "val3=4"},
+				{Key: "key2", Value: "val3,4"},
 			},
-			wantInHeader: []string{"key2=val3%3D4"},
+			wantInHeader: []string{"key2=val3%2C4"},
 		},
 		{
 			name: "with properties",

sdk/metric/EXPERIMENTAL.md

@@ -0,0 +1,50 @@
+# Experimental Features
+
+The metric SDK contains features that have not yet stabilized in the OpenTelemetry specification.
+These features are added to the OpenTelemetry Go metric SDK prior to stabilization in the specification so that users can start experimenting with them and provide feedback.
+
+These feature may change in backwards incompatible ways as feedback is applied.
+See the [Compatibility and Stability](#compatibility-and-stability) section for more information.
+
+## Features
+
+- [Cardinality Limit](#cardinality-limit)
+
+### Cardinality Limit
+
+The cardinality limit is the hard limit on the number of metric streams that can be collected for a single instrument.
+
+This experimental feature can be enabled by setting the `OTEL_GO_X_CARDINALITY_LIMIT` environment value.
+The value must be an integer value.
+All other values are ignored.
+
+If the value set is less than or equal to `0`, no limit will be applied.
+
+#### Examples
+
+Set the cardinality limit to 2000.
+
+```console
+export OTEL_GO_X_CARDINALITY_LIMIT=2000
+```
+
+Set an infinite cardinality limit (functionally equivalent to disabling the feature).
+
+```console
+export OTEL_GO_X_CARDINALITY_LIMIT=-1
+```
+
+Disable the cardinality limit.
+
+```console
+unset OTEL_GO_X_CARDINALITY_LIMIT
+```
+
+## Compatibility and Stability
+
+Experimental features do not fall within the scope of the OpenTelemetry Go versioning and stability [policy](../../VERSIONING.md).
+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.

sdk/metric/internal/aggregate/aggregate.go

@@ -44,6 +44,14 @@ type Builder[N int64 | float64] struct {
 	// Filter is the attribute filter the aggregate function will use on the
 	// input of measurements.
 	Filter attribute.Filter
+	// AggregationLimit is the cardinality limit of measurement attributes. Any
+	// measurement for new attributes once the limit has been reached will be
+	// aggregated into a single aggregate for the "otel.metric.overflow"
+	// attribute.
+	//
+	// If AggregationLimit is less than or equal to zero there will not be an
+	// aggregation limit imposed (i.e. unlimited attribute sets).
+	AggregationLimit int
 }
 
 func (b Builder[N]) filter(f Measure[N]) Measure[N] {
@@ -63,7 +71,7 @@ func (b Builder[N]) filter(f Measure[N]) Measure[N] {
 func (b Builder[N]) LastValue() (Measure[N], ComputeAggregation) {
 	// Delta temporality is the only temporality that makes semantic sense for
 	// a last-value aggregate.
-	lv := newLastValue[N]()
+	lv := newLastValue[N](b.AggregationLimit)
 
 	return b.filter(lv.measure), func(dest *metricdata.Aggregation) int {
 		// Ignore if dest is not a metricdata.Gauge. The chance for memory
@@ -79,7 +87,7 @@ func (b Builder[N]) LastValue() (Measure[N], ComputeAggregation) {
 // PrecomputedSum returns a sum aggregate function input and output. The
 // arguments passed to the input are expected to be the precomputed sum values.
 func (b Builder[N]) PrecomputedSum(monotonic bool) (Measure[N], ComputeAggregation) {
-	s := newPrecomputedSum[N](monotonic)
+	s := newPrecomputedSum[N](monotonic, b.AggregationLimit)
 	switch b.Temporality {
 	case metricdata.DeltaTemporality:
 		return b.filter(s.measure), s.delta
@@ -90,7 +98,7 @@ func (b Builder[N]) PrecomputedSum(monotonic bool) (Measure[N], ComputeAggregati
 
 // Sum returns a sum aggregate function input and output.
 func (b Builder[N]) Sum(monotonic bool) (Measure[N], ComputeAggregation) {
-	s := newSum[N](monotonic)
+	s := newSum[N](monotonic, b.AggregationLimit)
 	switch b.Temporality {
 	case metricdata.DeltaTemporality:
 		return b.filter(s.measure), s.delta
@@ -102,7 +110,7 @@ func (b Builder[N]) Sum(monotonic bool) (Measure[N], ComputeAggregation) {
 // ExplicitBucketHistogram returns a histogram aggregate function input and
 // output.
 func (b Builder[N]) ExplicitBucketHistogram(boundaries []float64, noMinMax, noSum bool) (Measure[N], ComputeAggregation) {
-	h := newHistogram[N](boundaries, noMinMax, noSum)
+	h := newHistogram[N](boundaries, noMinMax, noSum, b.AggregationLimit)
 	switch b.Temporality {
 	case metricdata.DeltaTemporality:
 		return b.filter(h.measure), h.delta
@@ -114,7 +122,7 @@ func (b Builder[N]) ExplicitBucketHistogram(boundaries []float64, noMinMax, noSu
 // ExponentialBucketHistogram returns a histogram aggregate function input and
 // output.
 func (b Builder[N]) ExponentialBucketHistogram(maxSize, maxScale int32, noMinMax, noSum bool) (Measure[N], ComputeAggregation) {
-	h := newExponentialHistogram[N](maxSize, maxScale, noMinMax, noSum)
+	h := newExponentialHistogram[N](maxSize, maxScale, noMinMax, noSum, b.AggregationLimit)
 	switch b.Temporality {
 	case metricdata.DeltaTemporality:
 		return b.filter(h.measure), h.delta

sdk/metric/internal/aggregate/aggregate_test.go

@@ -31,11 +31,15 @@ var (
 	keyUser    = "user"
 	userAlice  = attribute.String(keyUser, "Alice")
 	userBob    = attribute.String(keyUser, "Bob")
+	userCarol  = attribute.String(keyUser, "Carol")
+	userDave   = attribute.String(keyUser, "Dave")
 	adminTrue  = attribute.Bool("admin", true)
 	adminFalse = attribute.Bool("admin", false)
 
 	alice = attribute.NewSet(userAlice, adminTrue)
 	bob   = attribute.NewSet(userBob, adminFalse)
+	carol = attribute.NewSet(userCarol, adminFalse)
+	dave  = attribute.NewSet(userDave, adminFalse)
 
 	// Filtered.
 	attrFltr = func(kv attribute.KeyValue) bool {

sdk/metric/internal/aggregate/exponential_histogram.go

@@ -288,13 +288,14 @@ func (b *expoBuckets) downscale(delta int) {
 // newExponentialHistogram returns an Aggregator that summarizes a set of
 // measurements as an exponential histogram. Each histogram is scoped by attributes
 // and the aggregation cycle the measurements were made in.
-func newExponentialHistogram[N int64 | float64](maxSize, maxScale int32, noMinMax, noSum bool) *expoHistogram[N] {
+func newExponentialHistogram[N int64 | float64](maxSize, maxScale int32, noMinMax, noSum bool, limit int) *expoHistogram[N] {
 	return &expoHistogram[N]{
 		noSum:    noSum,
 		noMinMax: noMinMax,
 		maxSize:  int(maxSize),
 		maxScale: int(maxScale),
 
+		limit:  newLimiter[*expoHistogramDataPoint[N]](limit),
 		values: make(map[attribute.Set]*expoHistogramDataPoint[N]),
 
 		start: now(),
@@ -309,6 +310,7 @@ type expoHistogram[N int64 | float64] struct {
 	maxSize  int
 	maxScale int
 
+	limit    limiter[*expoHistogramDataPoint[N]]
 	values   map[attribute.Set]*expoHistogramDataPoint[N]
 	valuesMu sync.Mutex
 
@@ -324,6 +326,7 @@ func (e *expoHistogram[N]) measure(_ context.Context, value N, attr attribute.Se
 	e.valuesMu.Lock()
 	defer e.valuesMu.Unlock()
 
+	attr = e.limit.Attributes(attr, e.values)
 	v, ok := e.values[attr]
 	if !ok {
 		v = newExpoHistogramDataPoint[N](e.maxSize, e.maxScale, e.noMinMax, e.noSum)