Common Expression Language (CEL) sampler #1957

dol · 2025-06-11T15:28:34Z

This pull request introduces a new CelBasedSampler to the OpenTelemetry Java SDK, enabling advanced sampling rules using the Common Expression Language (CEL). It also includes updates to the existing RuleBasedRoutingSampler for consistency and clarity. Below is a summary of the most important changes grouped by theme:

New `CelBasedSampler` Implementation:

Added the CelBasedSampler class, which evaluates CEL expressions to make sampling decisions based on span attributes. It includes a fallback sampler and supports multiple expressions. (samplers/src/main/java/io/opentelemetry/contrib/sampler/CelBasedSampler.java)
Introduced the CelBasedSamplerBuilder to construct CelBasedSampler instances with methods for adding expressions and specifying actions (e.g., DROP or RECORD_AND_SAMPLE). (samplers/src/main/java/io/opentelemetry/contrib/sampler/CelBasedSamplerBuilder.java)
Added the CelBasedSamplingExpression class to encapsulate individual CEL expressions and their associated samplers. (samplers/src/main/java/io/opentelemetry/contrib/sampler/CelBasedSamplingExpression.java)
Implemented a declarative configuration provider for CelBasedSampler, enabling configuration through YAML files. (samplers/src/main/java/io/opentelemetry/contrib/sampler/internal/CelBasedSamplerComponentProvider.java)

# The fallback sampler to use if no expressions match.
fallback_sampler:
  always_on:
# List of CEL expressions to evaluate. Expressions are evaluated in order.
expressions:
  # The action to take when the expression evaluates to true. Must be one of: DROP, RECORD_AND_SAMPLE.
  - action: DROP
    # The CEL expression to evaluate. Must return a boolean.
    expression: attribute['url.path'].startsWith('/actuator')
  - action: RECORD_AND_SAMPLE
    expression: attribute['http.method'] == 'GET' && attribute['http.status_code'] < 400

Documentation Updates:

Updated samplers/README.md to document the new CelBasedSampler, including its usage, schema, and example configurations. (samplers/README.md) [1] [2]

Dependency Additions:

Added a dependency on the dev.cel:cel:0.9.0 library to enable CEL expression evaluation. (samplers/build.gradle.kts)

Updates to `RuleBasedRoutingSampler`:

Renamed SamplingRule to RuleBasedRoutingSamplingRule for clarity and updated all related references in the RuleBasedRoutingSampler and its builder. (samplers/src/main/java/io/opentelemetry/contrib/sampler/RuleBasedRoutingSampler.java, samplers/src/main/java/io/opentelemetry/contrib/sampler/RuleBasedRoutingSamplerBuilder.java, samplers/src/main/java/io/opentelemetry/contrib/sampler/RuleBasedRoutingSamplingRule.java) [1] [2] [3] [4] [5] [6] [7]

These changes collectively enhance the SDK's sampling capabilities, allowing users to define sophisticated sampling rules using CEL while maintaining compatibility with existing samplers.

linux-foundation-easycla · 2025-06-11T15:28:40Z

The committers listed above are authorized under a signed CLA.

✅ login: dol / name: Dominic Lüchinger (776abf3)

trask · 2025-06-11T17:26:37Z

@dol this looks nice!

@johnbley what do you think of CEL vs JEXL in the context of open-telemetry/opentelemetry-java-instrumentation#13590?

dol · 2025-06-12T07:00:09Z

Just a note to myself. I need to expand the test cases with the following addition.

Define multiple expressions to test the handling and ordering of expressions
- Add the same expression with DROP and RECORD_AND_SAMPLE. The first expression and action should be take affect.
- Add more complex expressions that pass the compile step and should work in the verify step like attribute['http.status_code'] < 400 and time based example to sample outside of business hours

johnbley · 2025-06-12T12:17:32Z

@dol this looks nice!

@johnbley what do you think of CEL vs JEXL in the context of open-telemetry/opentelemetry-java-instrumentation#13590?

Very interesting! I'll take a look at it!

dol · 2025-06-12T13:56:01Z

Just a note to myself. I need to expand the test cases with the following addition.

* Define multiple expressions to test the handling and ordering of expressions
  
  * Add the same expression with DROP and RECORD_AND_SAMPLE. The first expression and action should be take affect.
  * Add more complex expressions that pass the compile step and should work in the verify step like `attribute['http.status_code'] < 400` and time based example to sample outside of business hours

As I refined the tests I found some edge cases in the setup and mapping of the CEL engine. I'll mark the PR as work in progress. Sorry for that.

trask · 2025-06-12T14:24:36Z

I'll mark the PR as work in progress. Sorry for that.

no worries! you can click "Convert to draft" (hidden under the list of reviewers), and then when you're ready you can click "Ready for review"

dol · 2025-06-18T06:02:37Z

@trask @jack-berg : I wanted you to give an update on the PR. As I was adding more tests cases to PR I encountered a problem with single/double quote parsing on the declarative config. First I though it's an issue with a complex expression input. But after digging deep into the source code of this project and opentelementry-java I figured out, that the https://opentelemetry.io/docs/specs/otel/configuration/data-model/#environment-variable-substitution implementation on top of snakeyaml can not handle a mix of single and double quotes very well.

I created the following bug report: open-telemetry/opentelemetry-java#7429

As the chances are very high that a complex expression will need to mix single and double quotes, this bug should be addressed first.

dol · 2025-06-19T06:14:37Z

open-telemetry/opentelemetry-java#7433 should fix this regression.

dol · 2025-06-23T22:13:25Z

The latest version added more unit tests and better coverage. I think the new CEL sampler is ready for an review.
The tests still require the open-telemetry/opentelemetry-java#7433 to be approved, merged and released.
Until then the build and tests will fail.

breedx-splk · 2025-07-07T21:24:52Z

Build is pretty broken. Can you look at this @dol thanks!

dol · 2025-07-07T22:17:54Z

The latest version added more unit tests and better coverage. I think the new CEL sampler is ready for an review. The tests still require the open-telemetry/opentelemetry-java#7433 to be approved, merged and released. Until then the build and tests will fail.

@breedx-splk I'm waiting for the v1.52.0 release, which should be released soon. This will fix all the broken tests.

dependencyManagement/build.gradle.kts

Adds new CelBasedSampler to the OpenTelemetry Java SDK, enabling advanced sampling rules using the Common Expression Language (CEL). It also includes updates to the existing RuleBasedRoutingSampler for consistency and clarity.

dol · 2025-08-06T09:57:37Z

@jack-berg @trask The PR is ready for review after the fix was merged and release ( open-telemetry/opentelemetry-java#7433 ) and the BOM version was bumped ( 850933f#diff-df7d51fc1db73056c56958a9784e26310dae8ec239fb940820f5ddea4b655693L5 )

breedx-splk

Thanks! I think this is an awesome addition that users will start trying immediately. I left a few comments/questions that I'd like to see addressed...but this is looking solid.

breedx-splk · 2025-08-25T20:51:30Z

samplers/README.md

+fallback_sampler:
+  always_on:


If this required or does it default to always_on if not present? Might be nice to mention that here?

breedx-splk · 2025-08-25T20:57:15Z

samplers/src/main/java/io/opentelemetry/contrib/sampler/CelBasedSamplingExpression.java

+  final CelAbstractSyntaxTree abstractSyntaxTree;
+  final String expression;
+  final Sampler delegate;


I believe our convention is to make these private and use explicit getters, or use @AutoValue with a create() method.

breedx-splk · 2025-08-25T21:01:15Z

...rc/main/java/io/opentelemetry/contrib/sampler/internal/CelBasedSamplerComponentProvider.java

+    DeclarativeConfigProperties fallbackModel = config.getStructured("fallback_sampler");
+    if (fallbackModel == null) {
+      throw new DeclarativeConfigException(
+          "cel_based sampler .fallback_sampler is required but is null");
+    }
+    Sampler fallbackSampler;
+    try {
+      fallbackSampler = DeclarativeConfiguration.createSampler(fallbackModel);
+    } catch (DeclarativeConfigException e) {
+      throw new DeclarativeConfigException(
+          "cel_based sampler failed to create .fallback_sampler sampler", e);
+    }


Factoring this out to a method called getFallbackModel() could probably help to shrink this long method and improve readability. 👍🏻

breedx-splk · 2025-08-25T21:05:16Z

samplers/README.md

+# The fallback sampler to use if no expressions match.
+fallback_sampler:
+  always_on:
+# List of CEL expressions to evaluate. Expressions are evaluated in order.


I think it would help to be very explicit. Calling out that it's in-order is great, but is it that the first expression to match is applied and the remaining do not get evaluated, or is it the last one to match "wins"?

breedx-splk · 2025-08-25T21:06:19Z

samplers/src/test/java/internal/CelBasedSamplerComponentProviderTest.java

+        DeclarativeConfiguration.parseAndCreate(
+            new ByteArrayInputStream(yaml.getBytes(StandardCharsets.UTF_8)));
+    Sampler sampler = openTelemetrySdk.getSdkTracerProvider().getSampler();
+    assertThat(sampler.toString())


I think it's fine for this first pass (shouldn't gate this PR), but testing through the toString() is a bit of an antipattern. We can look at ways of making that more testable later tho.

breedx-splk · 2025-08-25T21:09:00Z

samplers/src/test/java/internal/CelBasedSamplerComponentProviderTest.java

+      try {
+        builder.recordAndSample(expression);
+      } catch (CelValidationException e) {
+        // Delegate to the provider to handle the exception


Same comment as above about fail/catch.

breedx-splk · 2025-08-25T21:10:47Z

samplers/src/test/java/internal/CelBasedSamplerComponentProviderTest.java

+                + "  - action: DROP\n"
+                + "    expression: 'invalid cel expression!'\n",
+            "Failed to compile CEL expression: invalid cel expression!"));
+  }


Maybe I missed it, but it would be cool to add coverage for the case where expressions exists but is empty.

breedx-splk · 2025-08-25T21:14:40Z

samplers/src/test/java/io/opentelemetry/contrib/sampler/CelBasedSamplerTest.java

+            CelBasedSampler.celCompiler
+                .compile(
+                    "spanKind == 'SERVER' && attribute[\""
+                        + URL_FULL


This works because AttributeKey.toString() merely returns the key (String), but if the toString() one day had type information in it or something, this could fail. It can be made slightly more explicit/robust by using URL_FULL.getKey().

breedx-splk · 2025-08-25T21:14:54Z

samplers/src/test/java/io/opentelemetry/contrib/sampler/CelBasedSamplerTest.java

+            CelBasedSampler.celCompiler
+                .compile(
+                    "spanKind == 'SERVER' && attribute[\""
+                        + URL_FULL


same comment as above

breedx-splk · 2025-08-25T21:26:36Z

samplers/src/test/java/io/opentelemetry/contrib/sampler/CelBasedSamplerTest.java

+@ExtendWith(MockitoExtension.class)
+class CelBasedSamplerTest {
+  private static final String SPAN_NAME = "MySpanName";
+  private static final SpanKind SPAN_KIND = SpanKind.SERVER;


In some of the tests at least, this additional redirection of an existing constant makes the tests slightly harder to read/understand. I'd just inline SpanKind.SERVER instead of having this indirection.

dol requested a review from a team June 11, 2025 15:28

github-actions bot assigned jack-berg and trask Jun 11, 2025

github-actions bot requested review from jack-berg and trask June 11, 2025 15:28

dol changed the title ~~Common Expression Language (CEL) sampler~~ [WIP] Common Expression Language (CEL) sampler Jun 12, 2025

dol marked this pull request as draft June 12, 2025 15:51

dol force-pushed the feature/cel-sampler branch from c21379b to a6e408c Compare June 23, 2025 22:09

dol changed the title ~~[WIP] Common Expression Language (CEL) sampler~~ Common Expression Language (CEL) sampler Jun 25, 2025

dol marked this pull request as ready for review June 25, 2025 05:48

dol commented Jul 19, 2025

View reviewed changes

dependencyManagement/build.gradle.kts Outdated Show resolved Hide resolved

github-actions bot assigned jsuereth and zeitlinger Jul 20, 2025

dol force-pushed the feature/cel-sampler branch from 154ab66 to 776abf3 Compare July 21, 2025 20:08

breedx-splk reviewed Aug 25, 2025

View reviewed changes

Common Expression Language (CEL) sampler #1957

Are you sure you want to change the base?

Common Expression Language (CEL) sampler #1957

Uh oh!

Conversation

dol commented Jun 11, 2025

New CelBasedSampler Implementation:

Documentation Updates:

Dependency Additions:

Updates to RuleBasedRoutingSampler:

Uh oh!

linux-foundation-easycla bot commented Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

trask commented Jun 11, 2025

Uh oh!

dol commented Jun 12, 2025

Uh oh!

johnbley commented Jun 12, 2025

Uh oh!

dol commented Jun 12, 2025

Uh oh!

trask commented Jun 12, 2025

Uh oh!

dol commented Jun 18, 2025

Uh oh!

dol commented Jun 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dol commented Jun 23, 2025

Uh oh!

breedx-splk commented Jul 7, 2025

Uh oh!

dol commented Jul 7, 2025

Uh oh!

Uh oh!

dol commented Aug 6, 2025

Uh oh!

breedx-splk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

New `CelBasedSampler` Implementation:

Updates to `RuleBasedRoutingSampler`:

linux-foundation-easycla bot commented Jun 11, 2025 •

edited

Loading

dol commented Jun 19, 2025 •

edited

Loading