Implement span suppression strategies (#1599)

* Implement span suppression strategies

Noop: does not suppress anything
SpanKind: suppresses nested spans with the same span kind (except for internal)
SemConv: attempts to guess and suppress the semantic convention that is represented by the span

* Fix style

* Add `experimental`/`internal` annotation

* Move `SpanSuppressionStrategy` and related classes to SDK

* Update examples to avoid usage of internal classes

* Move `SpanSuppression` namespace to `API\Trace`

* Add override attributes

* Prefilter semantic conventions based on sampling relevant attributes

* Add basic span suppression test

* Only inspect sampling relevant attributes

* Inverse attribute masks

* Ignore extra attributes if otherwise no semconv is matched

* Return singletons where possible

* Bump API dependency

* Fix span kinds without semantic conventions

Author: Nevay

Trace/Span.php

@@ -14,6 +14,8 @@
 use OpenTelemetry\SDK\Common\Exception\StackTraceFormatter;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface;
 use OpenTelemetry\SDK\Resource\ResourceInfo;
+use OpenTelemetry\SDK\Trace\SpanSuppression\NoopSuppressionStrategy\NoopSuppression;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppression;
 use Throwable;
 
 final class Span extends API\Span implements ReadWriteSpanInterface
@@ -44,6 +46,7 @@ private function __construct(
         private array $links,
         private int $totalRecordedLinks,
         private readonly int $startEpochNanos,
+        private readonly SpanSuppression $spanSuppression,
     ) {
         $this->status = StatusData::unset();
     }
@@ -73,6 +76,7 @@ public static function startSpan(
         array $links,
         int $totalRecordedLinks,
         int $startEpochNanos,
+        SpanSuppression $spanSuppression = new NoopSuppression(),
     ): self {
         $span = new self(
             $name,
@@ -86,7 +90,8 @@ public static function startSpan(
             $attributesBuilder,
             $links,
             $totalRecordedLinks,
-            $startEpochNanos !== 0 ? $startEpochNanos : Clock::getDefault()->now()
+            $startEpochNanos !== 0 ? $startEpochNanos : Clock::getDefault()->now(),
+            $spanSuppression,
         );
 
         // Call onStart here to ensure the span is fully initialized.
@@ -111,6 +116,12 @@ public static function formatStackTrace(Throwable $e, ?array &$seen = null): str
         return StackTraceFormatter::format($e);
     }
 
+    #[\Override]
+    public function storeInContext(ContextInterface $context): ContextInterface
+    {
+        return $this->spanSuppression->suppress(parent::storeInContext($context));
+    }
+
     /** @inheritDoc */
     #[\Override]
     public function getContext(): API\SpanContextInterface

Trace/SpanBuilder.php

@@ -10,6 +10,8 @@
 use OpenTelemetry\Context\ContextInterface;
 use OpenTelemetry\SDK\Common\Attribute\AttributesBuilderInterface;
 use OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface;
+use OpenTelemetry\SDK\Trace\SpanSuppression\NoopSuppressionStrategy\NoopSuppressor;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressor;
 
 final class SpanBuilder implements API\SpanBuilderInterface
 {
@@ -32,6 +34,7 @@ public function __construct(
         private readonly string $spanName,
         private readonly InstrumentationScopeInterface $instrumentationScope,
         private readonly TracerSharedState $tracerSharedState,
+        private readonly SpanSuppressor $spanSuppressor = new NoopSuppressor(),
     ) {
         $this->attributesBuilder = $this->tracerSharedState->getSpanLimits()->getAttributesFactory()->builder();
     }
@@ -125,6 +128,11 @@ public function startSpan(): API\SpanInterface
         $parentSpan = Span::fromContext($parentContext);
         $parentSpanContext = $parentSpan->getContext();
 
+        $spanSuppression = $this->spanSuppressor->resolveSuppression($this->spanKind, $this->attributesBuilder->build()->toArray());
+        if ($spanSuppression->isSuppressed($parentContext)) {
+            return Span::wrap($parentSpanContext);
+        }
+
         $spanId = $this->tracerSharedState->getIdGenerator()->generateSpanId();
 
         if (!$parentSpanContext->isValid()) {
@@ -155,6 +163,7 @@ public function startSpan(): API\SpanInterface
         );
 
         if (!in_array($samplingDecision, [SamplingResult::RECORD_AND_SAMPLE, SamplingResult::RECORD_ONLY], true)) {
+            // TODO must suppress no-op spans too
             return Span::wrap($spanContext);
         }
 
@@ -176,7 +185,8 @@ public function startSpan(): API\SpanInterface
             $attributesBuilder,
             $this->links,
             $this->totalNumberOfLinksAdded,
-            $this->startEpochNanos
+            $this->startEpochNanos,
+            $spanSuppression,
         );
     }
 }

Trace/SpanSuppression/NoopSuppressionStrategy/NoopSuppression.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\NoopSuppressionStrategy;
+
+use OpenTelemetry\Context\ContextInterface;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppression;
+
+/**
+ * @internal
+ */
+final class NoopSuppression implements SpanSuppression
+{
+    #[\Override]
+    public function isSuppressed(ContextInterface $context): bool
+    {
+        return false;
+    }
+
+    #[\Override]
+    public function suppress(ContextInterface $context): ContextInterface
+    {
+        return $context;
+    }
+}

Trace/SpanSuppression/NoopSuppressionStrategy/NoopSuppressionStrategy.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\NoopSuppressionStrategy;
+
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressionStrategy;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressor;
+
+/**
+ * @experimental
+ */
+final class NoopSuppressionStrategy implements SpanSuppressionStrategy
+{
+    #[\Override]
+    public function getSuppressor(string $name, ?string $version, ?string $schemaUrl): SpanSuppressor
+    {
+        static $suppressor = new NoopSuppressor();
+
+        return $suppressor;
+    }
+}

Trace/SpanSuppression/NoopSuppressionStrategy/NoopSuppressor.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\NoopSuppressionStrategy;
+
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppression;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressor;
+
+/**
+ * @internal
+ */
+final class NoopSuppressor implements SpanSuppressor
+{
+    #[\Override]
+    public function resolveSuppression(int $spanKind, array $attributes): SpanSuppression
+    {
+        static $suppression = new NoopSuppression();
+
+        return $suppression;
+    }
+}

Trace/SpanSuppression/SemanticConventionSuppressionStrategy/CompiledSemanticConventionAttribute.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\SemanticConventionSuppressionStrategy;
+
+/**
+ * @internal
+ */
+final class CompiledSemanticConventionAttribute
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly int $notSamplingRelevantIn,
+        public readonly int $includedIn,
+    ) {
+    }
+}

Trace/SpanSuppression/SemanticConventionSuppressionStrategy/SemanticConventionSuppression.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\SemanticConventionSuppressionStrategy;
+
+use OpenTelemetry\Context\ContextInterface;
+use OpenTelemetry\Context\ContextKeyInterface;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppression;
+
+/**
+ * @internal
+ */
+final class SemanticConventionSuppression implements SpanSuppression
+{
+    public function __construct(
+        private readonly ContextKeyInterface $contextKey,
+        private readonly array $semanticConventions,
+    ) {
+    }
+
+    #[\Override]
+    public function isSuppressed(ContextInterface $context): bool
+    {
+        $suppressedConventions = $context->get($this->contextKey);
+        if ($suppressedConventions === null) {
+            return false;
+        }
+
+        foreach ($this->semanticConventions as $semanticConvention) {
+            if (!isset($suppressedConventions[$semanticConvention])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    #[\Override]
+    public function suppress(ContextInterface $context): ContextInterface
+    {
+        $suppressedConventions = $context->get($this->contextKey) ?? [];
+        foreach ($this->semanticConventions as $semanticConvention) {
+            $suppressedConventions[$semanticConvention] ??= true;
+        }
+
+        return $context->with($this->contextKey, $suppressedConventions);
+    }
+}

Trace/SpanSuppression/SemanticConventionSuppressionStrategy/SemanticConventionSuppressionContextKey.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\SemanticConventionSuppressionStrategy;
+
+use OpenTelemetry\Context\ContextKeyInterface;
+
+/**
+ * @implements ContextKeyInterface<array<string, true>>
+ *
+ * @internal
+ */
+enum SemanticConventionSuppressionContextKey implements ContextKeyInterface
+{
+    case Internal;
+    case Client;
+    case Server;
+    case Producer;
+    case Consumer;
+}

Trace/SpanSuppression/SemanticConventionSuppressionStrategy/SemanticConventionSuppressionStrategy.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\SpanSuppression\SemanticConventionSuppressionStrategy;
+
+use function array_key_last;
+use function array_merge;
+use function assert;
+use OpenTelemetry\API\Trace\SpanSuppression\SemanticConventionResolver;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressionStrategy;
+use OpenTelemetry\SDK\Trace\SpanSuppression\SpanSuppressor;
+use function strcspn;
+use function strlen;
+
+/**
+ * @experimental
+ */
+final class SemanticConventionSuppressionStrategy implements SpanSuppressionStrategy
+{
+    /**
+     * @param iterable<SemanticConventionResolver> $resolvers
+     */
+    public function __construct(
+        private readonly iterable $resolvers,
+    ) {
+    }
+
+    #[\Override]
+    public function getSuppressor(string $name, ?string $version, ?string $schemaUrl): SpanSuppressor
+    {
+        $semanticConventions = [];
+        foreach ($this->resolvers as $resolver) {
+            $semanticConventions[] = $resolver->resolveSemanticConventions($name, $version, $schemaUrl);
+        }
+        $semanticConventions = array_merge(...$semanticConventions);
+
+        $lookup = [];
+        foreach ($semanticConventions as $semanticConvention) {
+            foreach ($semanticConvention->samplingAttributes as $attribute) {
+                assert(strcspn($attribute, '*?') === strlen($attribute));
+                $lookup[$semanticConvention->spanKind][$attribute] ??= [0, 0];
+            }
+        }
+
+        $compiledSemanticConventions = [];
+        foreach ($semanticConventions as $semanticConvention) {
+            $attributes = new WildcardPattern();
+            foreach ($semanticConvention->samplingAttributes as $attribute) {
+                $attributes->add($attribute);
+            }
+            foreach ($semanticConvention->attributes as $attribute) {
+                $attributes->add($attribute);
+            }
+
+            $compiledSemanticConventions[$semanticConvention->spanKind][] = $semanticConvention->name;
+            $i = array_key_last($compiledSemanticConventions[$semanticConvention->spanKind]);
+
+            foreach ($semanticConvention->samplingAttributes as $attribute) {
+                $lookup[$semanticConvention->spanKind][$attribute][0] |= 1 << $i;
+            }
+            foreach ($lookup[$semanticConvention->spanKind] as $attribute => $_) {
+                if (!$attributes->matches($attribute)) {
+                    $lookup[$semanticConvention->spanKind][$attribute][1] |= 1 << $i;
+                }
+            }
+        }
+
+        $compiledLookupAttributes = [];
+        foreach ($lookup as $spanKind => $attributes) {
+            foreach ($attributes as $attribute => $masks) {
+                $compiledLookupAttributes[$spanKind][] = new CompiledSemanticConventionAttribute($attribute, ~$masks[0], ~$masks[1]);
+            }
+        }
+
+        return new SemanticConventionSuppressor($compiledSemanticConventions, $compiledLookupAttributes);
+    }
+}