attribute-based sampler

composer.json

@@ -75,6 +75,7 @@
     },
     "require-dev": {
         "ext-grpc": "*",
+        "ext-pcre": "*",
         "grpc/grpc": "^1.30",
         "assertwell/phpunit-global-state": "^0.2.2",
         "composer/xdebug-handler": "^2.0",

examples/traces/features/attribute_based_sampling.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Example;
+
+require __DIR__ . '/../../../vendor/autoload.php';
+
+use OpenTelemetry\SDK\Trace\TracerProviderFactory;
+use OpenTelemetry\SemConv\TraceAttributes;
+
+//@see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md
+putenv('OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0');
+putenv('OTEL_SERVICE_NAME=example-app');
+putenv('OTEL_PHP_DETECTORS=none');
+putenv('OTEL_LOG_LEVEL=warning');
+putenv('OTEL_TRACES_SAMPLER=parentbased,attribute,traceidratio');
+putenv('OTEL_TRACES_SAMPLER_ARG=attribute.name=url.path,attribute.mode=deny,attribute.pattern=\/health$|\/test$,traceidratio.probability=1.0');
+putenv('OTEL_TRACES_EXPORTER=console');
+
+echo 'Starting attribute-based sampler example' . PHP_EOL;
+
+$tracerProvider = (new TracerProviderFactory())->create();
+
+$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php');
+
+echo 'Starting Tracer' . PHP_EOL;
+
+$span = $tracer->spanBuilder('root')->setAttribute(TraceAttributes::URL_PATH, '/health')->startSpan();
+$scope = $span->activate();
+
+try {
+    //this span will be sampled iff the root was sampled (parent-based)
+    $tracer->spanBuilder('child')->startSpan()->end();
+} finally {
+    $scope->detach();
+}
+$span->end();
+
+$tracerProvider->shutdown();

src/SDK/Common/Configuration/KnownValues.php

@@ -34,6 +34,8 @@ interface KnownValues
     public const VALUE_ALWAYS_ON = 'always_on';
     public const VALUE_ALWAYS_OFF = 'always_off';
     public const VALUE_TRACE_ID_RATIO = 'traceidratio';
+    public const VALUE_ATTRIBUTE = 'attribute';
+    public const VALUE_PARENT_BASED = 'parentbased';
     public const VALUE_PARENT_BASED_ALWAYS_ON = 'parentbased_always_on';
     public const VALUE_PARENT_BASED_ALWAYS_OFF = 'parentbased_always_off';
     public const VALUE_PARENT_BASED_TRACE_ID_RATIO = 'parentbased_traceidratio';

src/SDK/Trace/Sampler/AttributeBasedSampler.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\SDK\Trace\Sampler;
+
+use InvalidArgumentException;
+use OpenTelemetry\API\Behavior\LogsMessagesTrait;
+use OpenTelemetry\Context\ContextInterface;
+use OpenTelemetry\SDK\Common\Attribute\AttributesInterface;
+use OpenTelemetry\SDK\Trace\SamplerInterface;
+use OpenTelemetry\SDK\Trace\SamplingResult;
+
+/**
+ * @phan-file-suppress PhanParamTooFewUnpack
+ *
+ * Attribute-based sampler. This sampler should be called after a ParentBased sampler, and requires
+ * another sampler (such as AlwaysOnSampler).
+ * For example, ParentBased,AttributeBased(<deny if url.path attribute matches /health>),TradeIdRatio(0.5) means
+ * 1. Trace if parent is already sampled; otherwise
+ * 2. Do not sample if url.path attribute is set and matches /health; otherwise
+ * 3. Sample 50% of traces
+ *
+ * Two modes exist:
+ * "allow" mode: always sample if attribute exists and matches the pattern, else do not sample
+ * "deny" mode: do not sample if attribute exists and matches the pattern, else defer to next sampler
+ */
+class AttributeBasedSampler implements SamplerInterface
+{
+    use LogsMessagesTrait;
+
+    public const ALLOW = 'allow';
+    public const DENY = 'deny';
+    public const MODES = [
+        self::ALLOW,
+        self::DENY,
+    ];
+
+    private SamplerInterface $delegate;
+    private string $mode;
+    private string $attribute;
+    private string $pattern;
+
+    /**
+     * @param SamplerInterface $delegate The sampler to defer to if a decision is not made by this sampler
+     * @param string $mode Sampling mode (deny or allow)
+     * @param string $attribute The SemConv trace attribute to test against, eg http.path, http.method
+     * @param string $pattern The PCRE regex pattern to match against, eg /\/health$|\/test$/
+     */
+    public function __construct(SamplerInterface $delegate, string $mode, string $attribute, string $pattern)
+    {
+        if (!in_array($mode, self::MODES)) {
+            throw new InvalidArgumentException('Unknown Attribute sampler mode: ' . $mode);
+        }
+        $this->delegate = $delegate;
+        $this->mode = $mode;
+        $this->attribute = $attribute;
+        $this->pattern = $pattern;
+    }
+
+    public function shouldSample(ContextInterface $parentContext, string $traceId, string $spanName, int $spanKind, AttributesInterface $attributes, array $links): SamplingResult
+    {
+        switch ($this->mode) {
+            case self::ALLOW:
+                if (!$attributes->has($this->attribute)) {
+                    return new SamplingResult(SamplingResult::DROP);
+                }
+                if ($this->matches((string) $attributes->get($this->attribute))) {
+                    return new SamplingResult(SamplingResult::RECORD_AND_SAMPLE);
+                }
+
+                break;
+            case self::DENY:
+                if (!$attributes->has($this->attribute)) {
+                    break;
+                }
+                if ($this->matches((string) $attributes->get($this->attribute))) {
+                    return new SamplingResult(SamplingResult::DROP);
+                }
+
+                break;
+            default:
+                //do nothing
+        }
+
+        return $this->delegate->shouldSample(...func_get_args());
+    }
+
+    /**
+     * @todo call preg_last_error_msg directly after 7.4 support dropped
+     * @phan-suppress PhanUndeclaredFunctionInCallable
+     */
+    private function matches(string $value): bool
+    {
+        $result = @preg_match($this->pattern, $value);
+        if ($result === false) {
+            self::logWarning('Error when pattern matching attribute', [
+                'attribute.name' => $this->attribute,
+                'attribute.value' => $value,
+                'pattern' => $this->pattern,
+                'error' => function_exists('preg_last_error_msg') ? call_user_func('preg_last_error_msg') : '',
+            ]);
+
+            return false;
+        }
+
+        return (bool) $result;
+    }
+
+    public function getDescription(): string
+    {
+        return sprintf('AttributeSampler{mode=%s,attribute=%s,pattern=%s}+%s', $this->mode, $this->attribute, $this->pattern, $this->delegate->getDescription());
+    }
+}

src/SDK/Trace/SamplerFactory.php

@@ -10,6 +10,7 @@
 use OpenTelemetry\SDK\Common\Configuration\Variables as Env;
 use OpenTelemetry\SDK\Trace\Sampler\AlwaysOffSampler;
 use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
+use OpenTelemetry\SDK\Trace\Sampler\AttributeBasedSampler;
 use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
 use OpenTelemetry\SDK\Trace\Sampler\TraceIdRatioBasedSampler;
 
@@ -20,6 +21,12 @@ class SamplerFactory
     public function create(): SamplerInterface
     {
         $name = Configuration::getString(Env::OTEL_TRACES_SAMPLER);
+        if (strpos($name, ',') !== false) {
+            $parts = explode(',', $name);
+            $arg = Configuration::has(Env::OTEL_TRACES_SAMPLER_ARG) ? Configuration::getString(Env::OTEL_TRACES_SAMPLER_ARG) : '';
+
+            return $this->buildCompositeSampler($parts, $arg);
+        }
 
         if (strpos($name, self::TRACEIDRATIO_PREFIX) !== false) {
             $arg = Configuration::getRatio(Env::OTEL_TRACES_SAMPLER_ARG);
@@ -45,4 +52,72 @@ public function create(): SamplerInterface
                 throw new InvalidArgumentException(sprintf('Unknown sampler: %s', $name));
         }
     }
+
+    private function buildCompositeSampler(array $names, string $args): SamplerInterface
+    {
+        $sampler = null;
+        foreach (array_reverse($names) as $name) {
+            $sampler = $this->buildSampler($name, $args, $sampler);
+        }
+        assert($sampler !== null);
+
+        return $sampler;
+    }
+
+    private function buildSampler(string $name, string $args, ?SamplerInterface $next): SamplerInterface
+    {
+        switch ($name) {
+            case Values::VALUE_ALWAYS_ON:
+                return new AlwaysOnSampler();
+            case Values::VALUE_ALWAYS_OFF:
+                return new AlwaysOffSampler();
+            case Values::VALUE_PARENT_BASED:
+                assert($next !== null);
+
+                return new ParentBased($next);
+            case Values::VALUE_TRACE_ID_RATIO:
+                if (strpos($args, '=') !== false) {
+                    $probability = $this->splitArgs($args)[$name]['probability'] ?? null;
+                    if ($probability === null) {
+                        throw new InvalidArgumentException(sprintf('%s.probability=(numeric) not found in %s', $name, Env::OTEL_TRACES_SAMPLER_ARG));
+                    }
+                } else {
+                    //per specification, args may hold a single value
+                    $probability = $args;
+                }
+
+                return new TraceIdRatioBasedSampler((float) $probability);
+            case Values::VALUE_ATTRIBUTE:
+                $split = $this->splitArgs($args)[$name];
+                assert($next !== null);
+
+                return new AttributeBasedSampler($next, $split['mode'], $split['name'], sprintf('/%s/', $split['pattern']));
+
+            default:
+                //@todo check a registry to support 3rd party samplers
+                throw new InvalidArgumentException('Unknown sampler: ' . $name);
+        }
+    }
+
+    /**
+     * Split arguments from <name>.<key>=<value>,<name2>.<key2>=<value2> into an associative array
+     */
+    private function splitArgs(string $args): array
+    {
+        $return = [];
+        $parts = explode(',', $args);
+        foreach ($parts as $part) {
+            $equals = strpos($part, '=');
+            if ($equals === false) {
+                throw new InvalidArgumentException('Error parsing sampler arguments');
+            }
+            [$name, $key] = explode('.', substr($part, 0, $equals));
+            if (!array_key_exists($name, $return)) {
+                $return[$name] = [];
+            }
+            $return[$name][$key] = substr($part, $equals + 1);
+        }
+
+        return $return;
+    }
 }

src/SDK/composer.json

@@ -19,6 +19,7 @@
     "require": {
         "php": "^7.4 || ^8.0",
         "ext-json": "*",
+        "ext-pcre": "*",
         "open-telemetry/api": "^1.0",
         "open-telemetry/context": "^1.0",
         "open-telemetry/sem-conv": "^1.0",