open-telemetry
diff --git a/‎.chloggen/add-tracing-tailsampling.yaml‎
Lines changed: 30 additions & 0 deletions b/‎.chloggen/add-tracing-tailsampling.yaml‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎processor/tailsamplingprocessor/internal/telemetry/preallocated_span_attribute.go‎
Lines changed: 61 additions & 0 deletions b/‎processor/tailsamplingprocessor/internal/telemetry/preallocated_span_attribute.go‎
Lines changed: 61 additions & 0 deletions
diff --git a/‎processor/tailsamplingprocessor/internal/telemetry/preallocated_span_attribute_test.go‎
Lines changed: 192 additions & 0 deletions b/‎processor/tailsamplingprocessor/internal/telemetry/preallocated_span_attribute_test.go‎
Lines changed: 192 additions & 0 deletions
diff --git a/‎processor/tailsamplingprocessor/pkg/samplingpolicy/samplingpolicy.go‎
Lines changed: 24 additions & 0 deletions b/‎processor/tailsamplingprocessor/pkg/samplingpolicy/samplingpolicy.go‎
Lines changed: 24 additions & 0 deletions
@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: processor/tail_sampling
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add distributed tracing instrumentation to `tailsamplingprocessor` to provide visibility into trace processing behavior and policy evaluation"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [43931]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Adds trace spans for key operations:
+  - `tailsampling.ConsumeTraces`: Tracks incoming traces/spans count
+  - `tailsampling.samplingPolicyOnTick`: Records batch processing metrics and policy evaluation results
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]
@@ -0,0 +1,61 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package telemetry // import "github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor/internal/telemetry"
+
+import (
+	"go.opentelemetry.io/otel/attribute"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor/pkg/samplingpolicy"
+)
+
+// DecisionAttributes holds pre-allocated attribute.KeyValue for all decision types.
+// It provides O(1) access to pre-computed attributes using array indexing instead of map lookups,
+// eliminating runtime allocations during trace processing. The struct is immutable after construction
+// and safe for concurrent access.
+type DecisionAttributes struct {
+	key         attribute.Key         // The attribute key used for all decisions
+	attrs       [8]attribute.KeyValue // Array indexed by Decision value (0-7)
+	unknownAttr attribute.KeyValue    // Returned for invalid decisions
+}
+
+// NewDecisionAttributes creates a DecisionAttributes instance with pre-computed KeyValue pairs
+// for all 8 decision types defined in samplingpolicy.Decision.
+// Parameters:
+//   - attrKey: The attribute key to use for all decision attributes (e.g., "decision.final", "policy.decision")
+//
+// Example:
+//
+//	spanDecisionAttrs := NewDecisionAttributes(attribute.Key("decision.final"))
+//	attr := spanDecisionAttrs.Get(samplingpolicy.Sampled) // Returns pre-allocated KeyValue
+func NewDecisionAttributes(attrKey attribute.Key) *DecisionAttributes {
+	da := &DecisionAttributes{
+		key: attrKey,
+	}
+
+	// Pre-compute all 8 decision attributes
+	da.attrs[samplingpolicy.Unspecified] = attrKey.String(samplingpolicy.Unspecified.String())
+	da.attrs[samplingpolicy.Pending] = attrKey.String(samplingpolicy.Pending.String())
+	da.attrs[samplingpolicy.Sampled] = attrKey.String(samplingpolicy.Sampled.String())
+	da.attrs[samplingpolicy.NotSampled] = attrKey.String(samplingpolicy.NotSampled.String())
+	da.attrs[samplingpolicy.Dropped] = attrKey.String(samplingpolicy.Dropped.String())
+	da.attrs[samplingpolicy.Error] = attrKey.String(samplingpolicy.Error.String())
+	//nolint:staticcheck // InvertSampled is deprecated but we need to support existing decision values
+	da.attrs[samplingpolicy.InvertSampled] = attrKey.String(samplingpolicy.InvertSampled.String())
+	//nolint:staticcheck // InvertNotSampled is deprecated but we need to support existing decision values
+	da.attrs[samplingpolicy.InvertNotSampled] = attrKey.String(samplingpolicy.InvertNotSampled.String())
+
+	// Pre-compute the unknown attribute for out-of-bounds decisions
+	da.unknownAttr = attrKey.String("missing.preallocation")
+
+	return da
+}
+
+// Get returns the pre-allocated KeyValue for the given decision.
+func (d *DecisionAttributes) Get(decision samplingpolicy.Decision) attribute.KeyValue {
+	// Bounds check: valid decisions are 0-7 (inclusive)
+	if decision < 0 || decision >= samplingpolicy.Decision(len(d.attrs)) {
+		return d.unknownAttr
+	}
+	return d.attrs[decision]
+}
@@ -0,0 +1,192 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package telemetry
+
+import (
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel/attribute"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor/pkg/samplingpolicy"
+)
+
+func TestNewDecisionAttributes_AllDecisions(t *testing.T) {
+	attrKey := attribute.Key("decision.final")
+	da := NewDecisionAttributes(attrKey)
+
+	require.NotNil(t, da)
+
+	// Test all 8 valid decisions
+	testCases := []struct {
+		decision      samplingpolicy.Decision
+		expectedValue string
+	}{
+		{samplingpolicy.Unspecified, "unspecified"},
+		{samplingpolicy.Pending, "pending"},
+		{samplingpolicy.Sampled, "sampled"},
+		{samplingpolicy.NotSampled, "not_sampled"},
+		{samplingpolicy.Dropped, "dropped"},
+		{samplingpolicy.Error, "error"},
+		//nolint:staticcheck // Testing deprecated but still supported values
+		{samplingpolicy.InvertSampled, "invert_sampled"},
+		//nolint:staticcheck // Testing deprecated but still supported values
+		{samplingpolicy.InvertNotSampled, "invert_not_sampled"},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.expectedValue, func(t *testing.T) {
+			attr := da.Get(tc.decision)
+			assert.Equal(t, attrKey, attr.Key, "Key should match")
+			assert.Equal(t, tc.expectedValue, attr.Value.AsString(), "Value should match decision string")
+		})
+	}
+}
+
+func TestDecisionAttributes_Get_UnknownDecisions(t *testing.T) {
+	attrKey := attribute.Key("test.key")
+	da := NewDecisionAttributes(attrKey)
+
+	testCases := []struct {
+		name     string
+		decision samplingpolicy.Decision
+	}{
+		{"negative decision", samplingpolicy.Decision(-1)},
+		{"decision 8", samplingpolicy.Decision(8)},
+		{"decision 100", samplingpolicy.Decision(100)},
+		{"decision 255", samplingpolicy.Decision(255)},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			attr := da.Get(tc.decision)
+			assert.Equal(t, attrKey, attr.Key, "Key should match")
+			assert.Equal(t, "missing.preallocation", attr.Value.AsString(), "Should return unknown value")
+		})
+	}
+
+	// Verify unknownAttr is consistent across multiple calls
+	attr1 := da.Get(samplingpolicy.Decision(-1))
+	attr2 := da.Get(samplingpolicy.Decision(100))
+	assert.Equal(t, attr1.Value.AsString(), attr2.Value.AsString(), "Unknown attributes should be consistent")
+}
+
+func TestDecisionAttributes_StringConsistency(t *testing.T) {
+	attrKey := attribute.Key("policy.decision")
+	da := NewDecisionAttributes(attrKey)
+
+	// Verify each decision's attribute value matches its String() method
+	allDecisions := []samplingpolicy.Decision{
+		samplingpolicy.Unspecified,
+		samplingpolicy.Pending,
+		samplingpolicy.Sampled,
+		samplingpolicy.NotSampled,
+		samplingpolicy.Dropped,
+		samplingpolicy.Error,
+		samplingpolicy.InvertSampled,    //nolint:staticcheck // Testing deprecated but still supported values
+		samplingpolicy.InvertNotSampled, //nolint:staticcheck // Testing deprecated but still supported values
+	}
+
+	for _, decision := range allDecisions {
+		t.Run(decision.String(), func(t *testing.T) {
+			attr := da.Get(decision)
+			expectedString := decision.String()
+			actualString := attr.Value.AsString()
+			assert.Equal(t, expectedString, actualString,
+				"Decision %d: attribute value should match String() method", decision)
+		})
+	}
+}
+
+func TestDecisionAttributes_DifferentKeys(t *testing.T) {
+	key1 := attribute.Key("decision.final")
+	key2 := attribute.Key("policy.decision")
+
+	da1 := NewDecisionAttributes(key1)
+	da2 := NewDecisionAttributes(key2)
+
+	// Test with the same decision type but different keys
+	decision := samplingpolicy.Sampled
+
+	attr1 := da1.Get(decision)
+	attr2 := da2.Get(decision)
+
+	// Keys should be different
+	assert.NotEqual(t, attr1.Key, attr2.Key, "Keys should differ")
+	assert.Equal(t, key1, attr1.Key, "First attribute should use first key")
+	assert.Equal(t, key2, attr2.Key, "Second attribute should use second key")
+
+	// Values should be the same (both "sampled")
+	assert.Equal(t, attr1.Value.AsString(), attr2.Value.AsString(), "Values should be the same")
+	assert.Equal(t, "sampled", attr1.Value.AsString(), "Value should be 'sampled'")
+}
+
+func TestDecisionAttributes_Concurrent(t *testing.T) {
+	attrKey := attribute.Key("concurrent.test")
+	da := NewDecisionAttributes(attrKey)
+
+	// Number of goroutines and iterations
+	numGoroutines := 100
+	iterations := 1000
+
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+
+	// All valid decisions
+	validDecisions := []samplingpolicy.Decision{
+		samplingpolicy.Unspecified,
+		samplingpolicy.Pending,
+		samplingpolicy.Sampled,
+		samplingpolicy.NotSampled,
+		samplingpolicy.Dropped,
+		samplingpolicy.Error,
+		samplingpolicy.InvertSampled,    //nolint:staticcheck // Testing deprecated but still supported values
+		samplingpolicy.InvertNotSampled, //nolint:staticcheck // Testing deprecated but still supported values
+	}
+
+	// Spawn multiple goroutines that concurrently call Get()
+	for i := range numGoroutines {
+		go func(_ int) {
+			defer wg.Done()
+			for j := range iterations {
+				// Cycle through all valid decisions
+				decision := validDecisions[j%len(validDecisions)]
+				attr := da.Get(decision)
+
+				// Verify the returned attribute is valid
+				assert.Equal(t, attrKey, attr.Key)
+				assert.Equal(t, decision.String(), attr.Value.AsString())
+			}
+		}(i)
+	}
+
+	wg.Wait()
+}
+
+func TestDecisionAttributes_ZeroValueKey(t *testing.T) {
+	// Test with empty key (unusual but valid)
+	emptyKey := attribute.Key("")
+	da := NewDecisionAttributes(emptyKey)
+
+	attr := da.Get(samplingpolicy.Sampled)
+	assert.Equal(t, emptyKey, attr.Key, "Should work with empty key")
+	assert.Equal(t, "sampled", attr.Value.AsString(), "Value should still be correct")
+}
+
+func TestDecisionAttributes_ImmutabilityAfterConstruction(t *testing.T) {
+	attrKey := attribute.Key("immutable.test")
+	da := NewDecisionAttributes(attrKey)
+
+	// Get the same decision multiple times
+	attr1 := da.Get(samplingpolicy.Sampled)
+	attr2 := da.Get(samplingpolicy.Sampled)
+	attr3 := da.Get(samplingpolicy.Sampled)
+
+	// All should return the same value
+	assert.Equal(t, attr1.Value.AsString(), attr2.Value.AsString())
+	assert.Equal(t, attr2.Value.AsString(), attr3.Value.AsString())
+	assert.Equal(t, "sampled", attr1.Value.AsString())
+}
@@ -51,6 +51,30 @@ const (
 	InvertNotSampled
 )
 
+// String returns a string representation of the Decision.
+func (d Decision) String() string {
+	switch d {
+	case Unspecified:
+		return "unspecified"
+	case Pending:
+		return "pending"
+	case Sampled:
+		return "sampled"
+	case NotSampled:
+		return "not_sampled"
+	case Dropped:
+		return "dropped"
+	case Error:
+		return "error"
+	case InvertSampled:
+		return "invert_sampled"
+	case InvertNotSampled:
+		return "invert_not_sampled"
+	default:
+		return "unknown"
+	}
+}
+
 // Evaluator implements a tail-based sampling policy evaluator,
 // which makes a sampling decision for a given trace when requested.
 type Evaluator interface {