update rule-based sampler to config 0.4 (#377)

- update to work with config 0.4
- rename key to php_rule_based
- update documentation

Author: brettmc

README.md

@@ -1,16 +1,20 @@
-# Contrib Sampler
+# RuleBasedSampler
 
-Provides additional samplers that are not part of the official specification.
+Allows sampling based on a list of rule sets.
 
 ## Installation
 
 ```shell
 composer require open-telemetry/sampler-rule-based
 ```
 
-## RuleBasedSampler
+## Usage
 
-Allows sampling based on a list of rule sets. The first matching rule set will decide the sampling result.
+Provide a list of `RuleSet` instances and a fallback sampler to the `RuleBasedSampler` constructor. Each rule set
+contains a list of rules and a delegate sampler to execute if the rule matches. The rules are evaluated in the order
+they are defined. The first matching rule set will decide the sampling result.
+
+If no rules match, then the fallback sampler is used.
 
 ```php
 $sampler = new RuleBasedSampler(
@@ -27,12 +31,29 @@ $sampler = new RuleBasedSampler(
 );
 ```
 
-### Configuration
+## Configuration
 
-###### Example: drop spans for the /health endpoint
+The RuleBased sampler can be configured through [Declarative Configuration](https://opentelemetry.io/docs/specs/otel/configuration/#declarative-configuration), using the
+key `php_rule_based` under `tracer_provider.sampler.sampler`:
 
 ```yaml
-contrib_rule_based:
+file_format: "0.4"
+
+tracer_provider:
+  sampler:
+    php_rule_based:
+      rule_sets:
+        # ...
+      fallback:
+        # ...
+```
+
+### Examples
+
+Drop spans for the /health endpoint:
+
+```yaml
+php_rule_based:
     rule_sets:
     -   rules:
         -   span_kind: { kind: SERVER }
@@ -42,21 +63,21 @@ contrib_rule_based:
     fallback: # ...
 ```
 
-###### Example: sample spans with at least one sampled link
+Sample spans with at least one sampled link:
 
 ```yaml
-contrib_rule_based:
+php_rule_based:
     rule_sets:
     -   rules: [ link: { sampled: true } ]
         delegate:
             always_on: {}
     fallback: # ...
 ```
 
-###### Example: modeling parent based sampler as rule based sampler
+Modeling parent-based sampler as rule-based sampler:
 
 ```yaml
-rule_based:
+php_rule_based:
     rule_sets:
     -   rules: [ parent: { sampled: true, remote: true } ]
         delegate: # remote_parent_sampled
@@ -67,21 +88,4 @@ rule_based:
     -   rules: [ parent: { sampled: false, remote: false } ]
         delegate: # local_parent_not_sampled
     fallback: # root
-```
-
-## AlwaysRecordingSampler
-
-Records all spans to allow the usage of span processors that generate metrics from spans.
-
-```php
-$sampler = new AlwaysRecordingSampler(
-    new ParentBasedSampler(new AlwaysOnSampler()),
-);
-```
-
-### Configuration
-
-```yaml
-always_recording:
-    sampler: # ...
-```
+```

composer.json

@@ -7,7 +7,7 @@
         "php": "^8.1",
         "open-telemetry/api": "^1.1.0",
         "open-telemetry/sdk": "^1.1.0",
-        "open-telemetry/sdk-configuration": "^0.0.5"
+        "open-telemetry/sdk-configuration": "^0.0.9"
     },
     "require-dev": {
         "symfony/config": "^5.4 || ^6.4 || ^7.0",

src/ComponentProvider/SamplerRuleBased.php

@@ -13,6 +13,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\SDK\Trace\SamplerInterface;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplerInterface>
@@ -49,17 +50,17 @@ public function createPlugin(array $properties, Context $context): SamplerInterf
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('contrib_rule_based');
+        $node = $builder->arrayNode('php_rule_based');
 
         /** @psalm-suppress PossiblyNullReference */
         $node
             ->children()
                 ->arrayNode('rule_sets')
                     ->arrayPrototype()
                         ->children()
-                            ->append($registry->componentArrayList('rules', SamplingRule::class)->isRequired()->cannotBeEmpty())
+                            ->append($registry->componentList('rules', SamplingRule::class)->isRequired()->cannotBeEmpty())
                             ->append($registry->component('delegate', SamplerInterface::class)->isRequired())
                         ->end()
                     ->end()

src/ComponentProvider/SamplingRuleAttribute.php

@@ -11,6 +11,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule\AttributeRule;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplingRule>
@@ -33,9 +34,9 @@ public function createPlugin(array $properties, Context $context): SamplingRule
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('attribute');
+        $node = $builder->arrayNode('attribute');
 
         /** @psalm-suppress PossiblyNullReference */
         $node

src/ComponentProvider/SamplingRuleLink.php

@@ -10,6 +10,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule\LinkRule;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplingRule>
@@ -31,9 +32,9 @@ public function createPlugin(array $properties, Context $context): SamplingRule
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('link');
+        $node = $builder->arrayNode('link');
 
         /** @psalm-suppress PossiblyNullReference */
         $node

src/ComponentProvider/SamplingRuleParent.php

@@ -10,6 +10,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule\ParentRule;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplingRule>
@@ -31,9 +32,9 @@ public function createPlugin(array $properties, Context $context): SamplingRule
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('parent');
+        $node = $builder->arrayNode('parent');
 
         /** @psalm-suppress PossiblyNullReference */
         $node

src/ComponentProvider/SamplingRuleSpanKind.php

@@ -11,6 +11,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule\SpanKindRule;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplingRule>
@@ -36,9 +37,9 @@ public function createPlugin(array $properties, Context $context): SamplingRule
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('span_kind');
+        $node = $builder->arrayNode('span_kind');
 
         /** @psalm-suppress PossiblyNullReference */
         $node

src/ComponentProvider/SamplingRuleSpanName.php

@@ -11,6 +11,7 @@
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule;
 use OpenTelemetry\Contrib\Sampler\RuleBased\SamplingRule\SpanNameRule;
 use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\NodeBuilder;
 
 /**
  * @implements ComponentProvider<SamplingRule>
@@ -31,9 +32,9 @@ public function createPlugin(array $properties, Context $context): SamplingRule
         );
     }
 
-    public function getConfig(ComponentProviderRegistry $registry): ArrayNodeDefinition
+    public function getConfig(ComponentProviderRegistry $registry, NodeBuilder $builder): ArrayNodeDefinition
     {
-        $node = new ArrayNodeDefinition('span_name');
+        $node = $builder->arrayNode('span_name');
 
         /** @psalm-suppress PossiblyNullReference */
         $node

tests/Integration/config/sdk-config.yaml

@@ -1,8 +1,8 @@
-file_format: "0.3"
+file_format: "0.4"
 
 tracer_provider:
   sampler:
-    contrib_rule_based:
+    php_rule_based:
       rule_sets:
         - rules:
             - attribute: {key: is.important, pattern: ~false~ }