open-telemetry/sampler-rule-based

OpenTelemetry SDK rule-based sampler

0.1.0 2025-06-11 18:17 UTC

Requires

• php: ^8.1
• open-telemetry/api: ^1.1.0
• open-telemetry/sdk: ^1.1.0
• open-telemetry/sdk-configuration: ^0.0.9

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3
• phan/phan: ^5.0
• phpstan/phpstan: ^1.1
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^10 || ^11
• psalm/plugin-phpunit: ^0.19.2
• symfony/config: ^5.4 || ^6.4 || ^7.0
• symfony/yaml: ^6 || ^7
• vimeo/psalm: ^4|^5|6.4.0

Apache-2.0

• sdk
• sampler
• tracing
• opentelemetry
• otel

README

Allows sampling based on a list of rule sets.

Installation

composer require open-telemetry/sampler-rule-based

Usage

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.

$sampler = new RuleBasedSampler(
    [
        new RuleSet(
            [
                new SpanKindRule(Kind::Server),
                new AttributeRule('url.path', '~^/health$~'),
            ],
            new AlwaysOffSampler(),
        ),
    ],
    new AlwaysOnSampler(),
);

Configuration

The RuleBased sampler can be configured through Declarative Configuration, using the key php_rule_based under tracer_provider.sampler.sampler:

file_format: "0.4"

tracer_provider:
  sampler:
    php_rule_based:
      rule_sets:
        # ...
      fallback:
        # ...

Examples

Drop spans for the /health endpoint:

php_rule_based:
    rule_sets:
    -   rules:
        -   span_kind: { kind: SERVER }
        -   attribute: { key: url.path, pattern: ~^/health$~ }
        delegate:
            always_off: {}
    fallback: # ...

Sample spans with at least one sampled link:

php_rule_based:
    rule_sets:
    -   rules: [ link: { sampled: true } ]
        delegate:
            always_on: {}
    fallback: # ...

Modeling parent-based sampler as rule-based sampler:

php_rule_based:
    rule_sets:
    -   rules: [ parent: { sampled: true, remote: true } ]
        delegate: # remote_parent_sampled
    -   rules: [ parent: { sampled: false, remote: true } ]
        delegate: # remote_parent_not_sampled
    -   rules: [ parent: { sampled: true, remote: false } ]
        delegate: # local_parent_sampled
    -   rules: [ parent: { sampled: false, remote: false } ]
        delegate: # local_parent_not_sampled
    fallback: # root