feat(Samplers): New CEL based sampler with declarative config support

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.

Author: dol

samplers/README.md

@@ -5,14 +5,15 @@
 The following samplers support [declarative configuration](https://opentelemetry.io/docs/languages/java/configuration/#declarative-configuration):
 
 * `RuleBasedRoutingSampler`
+* `CelBasedSampler`
 
 To use:
 
 * Add a dependency on `io.opentelemetry.contrib:opentelemetry-samplers:<version>`
 * Follow the [instructions](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/incubator/README.md#declarative-configuration) to configure OpenTelemetry with declarative configuration.
-* Configure the `.tracer_provider.sampler` to include the `rule_based_routing` sampler.
+* Configure the `.tracer_provider.sampler` to include the `rule_based_routing` or `cel_based` sampler.
 
-NOTE: Not yet available for use with the OTEL java agent, but should be in the near future. Please check back for updates.
+## RuleBasedRoutingSampler
 
 Schema for `rule_based_routing` sampler:
 
@@ -59,6 +60,66 @@ tracer_provider:
               pattern: /actuator.*
 ```
 
+## CelBasedSampler
+
+The `CelBasedSampler` uses [Common Expression Language (CEL)](https://github.com/google/cel-spec) to create advanced sampling rules based on span attributes. CEL provides a powerful, yet simple expression language that allows you to create complex matching conditions.
+
+To use:
+
+* Add a dependency on `io.opentelemetry:opentelemetry-sdk-extension-incubator:<version>`
+* Follow the [instructions](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/incubator/README.md#file-configuration) to configure OpenTelemetry with declarative configuration.
+* Configure the `.tracer_provider.sampler` to include the `cel_based` sampler.
+
+Schema for `cel_based` sampler:
+
+```yaml
+# 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
+```
+
+Available variables in CEL expressions:
+
+* `name` (string): The span name
+* `spanKind` (string): The span kind (e.g., "SERVER", "CLIENT")
+* `attribute` (map): A map of span attributes
+
+Example of using `cel_based` sampler as the root sampler in `parent_based` sampler configuration:
+
+```yaml
+tracer_provider:
+  sampler:
+    parent_based:
+      root:
+        cel_based:
+          fallback_sampler:
+            always_on:
+          expressions:
+            # Drop health check endpoints
+            - action: DROP
+              expression: spanKind == 'SERVER' && attribute['url.path'].startsWith('/health')
+            # Drop actuator endpoints
+            - action: DROP
+              expression: spanKind == 'SERVER' && attribute['url.path'].startsWith('/actuator')
+            # Sample only HTTP GET requests with successful responses
+            - action: RECORD_AND_SAMPLE
+              expression: spanKind == 'SERVER' && attribute['http.method'] == 'GET' && attribute['http.status_code'] < 400
+            # Selectively sample based on span name
+            - action: RECORD_AND_SAMPLE
+              expression: name.contains('checkout') || name.contains('payment')
+            # Drop spans with specific name patterns
+            - action: DROP
+              expression: name.matches('.*internal.*') && spanKind == 'INTERNAL'
+```
+
 ## Component owners
 
 - [Jack Berg](https://github.com/jack-berg), New Relic

samplers/build.gradle.kts

@@ -9,6 +9,8 @@ otelJava.moduleName.set("io.opentelemetry.contrib.sampler")
 dependencies {
   api("io.opentelemetry:opentelemetry-sdk")
 
+  implementation("dev.cel:cel:0.11.0")
+
   compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
   compileOnly("io.opentelemetry:opentelemetry-api-incubator")
   compileOnly("io.opentelemetry:opentelemetry-sdk-extension-incubator")

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

@@ -0,0 +1,141 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.sampler;
+
+import static java.util.Objects.requireNonNull;
+
+import dev.cel.common.types.CelProtoTypes;
+import dev.cel.common.types.SimpleType;
+import dev.cel.compiler.CelCompiler;
+import dev.cel.compiler.CelCompilerFactory;
+import dev.cel.runtime.CelEvaluationException;
+import dev.cel.runtime.CelRuntime;
+import dev.cel.runtime.CelRuntimeFactory;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.SpanBuilder;
+import io.opentelemetry.api.trace.SpanKind;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.sdk.trace.data.LinkData;
+import io.opentelemetry.sdk.trace.samplers.Sampler;
+import io.opentelemetry.sdk.trace.samplers.SamplingResult;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+import java.util.regex.Pattern;
+
+/**
+ * This sampler accepts a list of {@link CelBasedSamplingExpression}s and tries to match every
+ * proposed span against those rules. Every rule describes a span's attribute, a pattern against
+ * which to match attribute's value, and a sampler that will make a decision about given span if
+ * match was successful.
+ *
+ * <p>Matching is performed by {@link Pattern}.
+ *
+ * <p>Provided span kind is checked first and if differs from the one given to {@link
+ * #builder(Sampler)}, the default fallback sampler will make a decision.
+ *
+ * <p>Note that only attributes that were set on {@link SpanBuilder} will be taken into account,
+ * attributes set after the span has been started are not used
+ *
+ * <p>If none of the rules matched, the default fallback sampler will make a decision.
+ */
+public final class CelBasedSampler implements Sampler {
+
+  private static final Logger logger = Logger.getLogger(CelBasedSampler.class.getName());
+
+  public static final CelCompiler celCompiler =
+      CelCompilerFactory.standardCelCompilerBuilder()
+          .addVar("name", SimpleType.STRING)
+          .addVar("traceId", SimpleType.STRING)
+          .addVar("spanKind", SimpleType.STRING)
+          .addVar("attribute", CelProtoTypes.createMap(CelProtoTypes.STRING, CelProtoTypes.DYN))
+          .setResultType(SimpleType.BOOL)
+          .build();
+
+  final CelRuntime celRuntime;
+
+  private final List<CelBasedSamplingExpression> expressions;
+  private final Sampler fallback;
+
+  public CelBasedSampler(List<CelBasedSamplingExpression> expressions, Sampler fallback) {
+    this.expressions = requireNonNull(expressions, "expressions must not be null");
+    this.expressions.forEach(
+        expr -> {
+          if (!expr.abstractSyntaxTree.isChecked()) {
+            throw new IllegalArgumentException(
+                "Expression and its AST is not checked: " + expr.expression);
+          }
+        });
+    this.fallback = requireNonNull(fallback);
+    this.celRuntime = CelRuntimeFactory.standardCelRuntimeBuilder().build();
+  }
+
+  public static CelBasedSamplerBuilder builder(Sampler fallback) {
+    return new CelBasedSamplerBuilder(
+        requireNonNull(fallback, "fallback sampler must not be null"), celCompiler);
+  }
+
+  @Override
+  public SamplingResult shouldSample(
+      Context parentContext,
+      String traceId,
+      String name,
+      SpanKind spanKind,
+      Attributes attributes,
+      List<LinkData> parentLinks) {
+
+    // Prepare the evaluation context with span data
+    Map<String, Object> evaluationContext = new HashMap<>();
+    evaluationContext.put("name", name);
+    evaluationContext.put("traceId", traceId);
+    evaluationContext.put("spanKind", spanKind.name());
+    evaluationContext.put("attribute", convertAttributesToMap(attributes));
+
+    for (CelBasedSamplingExpression expression : expressions) {
+      try {
+        CelRuntime.Program program = celRuntime.createProgram(expression.abstractSyntaxTree);
+        Object result = program.eval(evaluationContext);
+        // Happy path: Perform sampling based on the boolean result
+        if (result instanceof Boolean && ((Boolean) result)) {
+          return expression.delegate.shouldSample(
+              parentContext, traceId, name, spanKind, attributes, parentLinks);
+        }
+        // If result is not boolean, treat as false
+        logger.log(
+            Level.FINE,
+            "Expression '" + expression.expression + "' returned non-boolean result: " + result);
+      } catch (CelEvaluationException e) {
+        logger.log(
+            Level.FINE,
+            "Expression '" + expression.expression + "' evaluation error: " + e.getMessage());
+      }
+    }
+
+    return fallback.shouldSample(parentContext, traceId, name, spanKind, attributes, parentLinks);
+  }
+
+  /** Convert OpenTelemetry Attributes to a Map that CEL can work with */
+  private static Map<String, Object> convertAttributesToMap(Attributes attributes) {
+    Map<String, Object> map = new HashMap<>();
+    attributes.forEach(
+        (key, value) -> {
+          map.put(key.getKey(), value);
+        });
+    return map;
+  }
+
+  @Override
+  public String getDescription() {
+    return "CelBasedSampler{" + "fallback=" + fallback + ", expressions=" + expressions + '}';
+  }
+
+  @Override
+  public String toString() {
+    return getDescription();
+  }
+}

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

@@ -0,0 +1,68 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.sampler;
+
+import static java.util.Objects.requireNonNull;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import dev.cel.common.CelAbstractSyntaxTree;
+import dev.cel.common.CelValidationException;
+import dev.cel.compiler.CelCompiler;
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.sdk.trace.samplers.Sampler;
+import java.util.ArrayList;
+import java.util.List;
+
+public final class CelBasedSamplerBuilder {
+  private final CelCompiler celCompiler;
+  private final List<CelBasedSamplingExpression> expressions = new ArrayList<>();
+  private final Sampler defaultDelegate;
+
+  CelBasedSamplerBuilder(Sampler defaultDelegate, CelCompiler celCompiler) {
+    this.defaultDelegate = defaultDelegate;
+    this.celCompiler = celCompiler;
+  }
+
+  /**
+   * Use the provided sampler when the value of the provided {@link AttributeKey} matches the
+   * provided pattern.
+   */
+  @CanIgnoreReturnValue
+  public CelBasedSamplerBuilder customize(String expression, Sampler sampler)
+      throws CelValidationException {
+    CelAbstractSyntaxTree abstractSyntaxTree =
+        celCompiler.compile(requireNonNull(expression, "expression must not be null")).getAst();
+
+    expressions.add(
+        new CelBasedSamplingExpression(
+            requireNonNull(abstractSyntaxTree, "abstractSyntaxTree must not be null"),
+            requireNonNull(sampler, "sampler must not be null")));
+    return this;
+  }
+
+  /**
+   * Drop all spans when the value of the provided {@link AttributeKey} matches the provided
+   * pattern.
+   */
+  @CanIgnoreReturnValue
+  public CelBasedSamplerBuilder drop(String expression) throws CelValidationException {
+    return customize(expression, Sampler.alwaysOff());
+  }
+
+  /**
+   * Record and sample all spans when the value of the provided {@link AttributeKey} matches the
+   * provided pattern.
+   */
+  @CanIgnoreReturnValue
+  public CelBasedSamplerBuilder recordAndSample(String expression) throws CelValidationException {
+    return customize(expression, Sampler.alwaysOn());
+  }
+
+  /** Build the sampler based on the rules provided. */
+  public CelBasedSampler build() {
+    return new CelBasedSampler(expressions, defaultDelegate);
+  }
+}

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

@@ -0,0 +1,54 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.contrib.sampler;
+
+import static java.util.Objects.requireNonNull;
+
+import dev.cel.common.CelAbstractSyntaxTree;
+import io.opentelemetry.sdk.trace.samplers.Sampler;
+import java.util.Objects;
+import javax.annotation.Nullable;
+
+public class CelBasedSamplingExpression {
+  final CelAbstractSyntaxTree abstractSyntaxTree;
+  final String expression;
+  final Sampler delegate;
+
+  CelBasedSamplingExpression(CelAbstractSyntaxTree abstractSyntaxTree, Sampler delegate) {
+    this.abstractSyntaxTree = requireNonNull(abstractSyntaxTree);
+    this.expression = abstractSyntaxTree.getSource().getContent().toString();
+    this.delegate = requireNonNull(delegate);
+  }
+
+  @Override
+  public String toString() {
+    return "CelBasedSamplingExpression{"
+        + "expression='"
+        + expression
+        + "', delegate="
+        + delegate
+        + "}";
+  }
+
+  @Override
+  public boolean equals(@Nullable Object o) {
+    if (this == o) {
+      return true;
+    }
+    if (!(o instanceof CelBasedSamplingExpression)) {
+      return false;
+    }
+    CelBasedSamplingExpression that = (CelBasedSamplingExpression) o;
+    return Objects.equals(abstractSyntaxTree, that.abstractSyntaxTree)
+        && Objects.equals(expression, that.expression)
+        && Objects.equals(delegate, that.delegate);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(abstractSyntaxTree, expression, delegate);
+  }
+}