feat: hook builder options for dimension extraction (#391)

Signed-off-by: Kavindu Dodanduwa <[email protected]>
Signed-off-by: Kavindu Dodanduwa <[email protected]>

Author: Kavindu-Dodan

hooks/open-telemetry/README.md

@@ -33,7 +33,22 @@ The hook implementation is attached to `after`and `error` [hook stages](https://
 Both successful and failed flag evaluations will add a span event named `feature_flag` with evaluation details such as flag key, provider name and variant.
 Failed evaluations can be allowed to set span status to `ERROR`. You can configure this behavior through`TracesHookOptions`.
 
-Consider the following code example for usage,
+Further, you can write your own logic to extract custom dimensions from [flag evaluation metadata](https://github.com/open-feature/spec/blob/main/specification/types.md#flag-metadata) by setting a callback to `TracesHookOptions.dimensionExtractor`.
+Extracted dimensions will be added to successful falg evaluation spans.
+
+```java
+ TracesHookOptions options = TracesHookOptions.builder()
+             // configure a callback
+            .dimensionExtractor(metadata -> Attributes.builder()
+                    .put("boolean", metadata.getBoolean("boolean"))
+                    .put("integer", metadata.getInteger("integer"))
+                    .build()
+            ).build();
+
+    TracesHook tracesHook = new TracesHook(options);
+```
+
+Consider the following code example for a complete usage,
 
 ```java
 final Tracer tracer=... // derive Tracer from OpenTelemetry
@@ -95,3 +110,19 @@ OpenFeatureAPI api = OpenFeatureAPI.getInstance();
 // Register MetricsHook with custom dimensions
 api.addHooks(new MetricsHook(openTelemetry, customDimensions));
 ```
+
+Alternatively, you can wrtie your own extraction logic against [flag evaluation metadata](https://github.com/open-feature/spec/blob/main/specification/types.md#flag-metadata) by providing a callback to `TracesHookOptions.attributeSetter`.
+
+```java
+final OpenTelemetry openTelemetry = ... // OpenTelemetry API instance
+
+MetricHookOptions hookOptions = MetricHookOptions.builder()
+        // configure a callback
+        .attributeSetter(metadata -> Attributes.builder()
+            .put("boolean", metadata.getBoolean("boolean"))
+            .put("integer", metadata.getInteger("integer"))
+            .build())
+        .build();
+
+final MetricsHook metricHook = new MetricsHook(openTelemetry, hookOptions);
+```

hooks/open-telemetry/src/main/java/dev/openfeature/contrib/hooks/otel/MetricHookOptions.java

@@ -0,0 +1,33 @@
+package dev.openfeature.contrib.hooks.otel;
+
+import dev.openfeature.sdk.ImmutableMetadata;
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import io.opentelemetry.api.common.Attributes;
+import lombok.Builder;
+import lombok.Getter;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.function.Function;
+
+/**
+ * OpenTelemetry hook options.
+ */
+@Builder
+@Getter
+@SuppressFBWarnings(value = {"EI_EXPOSE_REP"}, justification = "Dimension list can be mutable")
+
+public class MetricHookOptions {
+
+    /**
+     * Custom handler to derive {@link Attributes} from flag evaluation metadata represented with
+     * {@link ImmutableMetadata}.
+     */
+    private Function<ImmutableMetadata, Attributes> attributeSetter;
+
+    /**
+     * List of {@link DimensionDescription} to be extracted from flag evaluation metadata.
+     */
+    @Builder.Default
+    private final List<DimensionDescription> setDimensions = Collections.emptyList();
+}

hooks/open-telemetry/src/main/java/dev/openfeature/contrib/hooks/otel/MetricsHook.java

@@ -17,6 +17,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.Function;
 
 import static dev.openfeature.contrib.hooks.otel.OTelCommons.ERROR_KEY;
 import static dev.openfeature.contrib.hooks.otel.OTelCommons.REASON_KEY;
@@ -42,6 +43,7 @@ public class MetricsHook implements Hook {
     private final LongCounter evaluationSuccessCounter;
     private final LongCounter evaluationErrorCounter;
     private final List<DimensionDescription> dimensionDescriptions;
+    private final Function<ImmutableMetadata, Attributes> extractor;
 
     /**
      * Construct a metric hook by providing an {@link OpenTelemetry} instance.
@@ -54,8 +56,18 @@ public MetricsHook(final OpenTelemetry openTelemetry) {
      * Construct a metric hook with {@link OpenTelemetry} instance and a list of {@link DimensionDescription}.
      * Provided dimensions are attempted to be extracted from ImmutableMetadata attached to
      * {@link FlagEvaluationDetails}.
+     *
+     * @deprecated - This constructor is deprecated. Please use {@link MetricHookOptions} based options
      */
+    @Deprecated
     public MetricsHook(final OpenTelemetry openTelemetry, final List<DimensionDescription> dimensions) {
+        this(openTelemetry, MetricHookOptions.builder().setDimensions(dimensions).build());
+    }
+
+    /**
+     * Construct a metric hook with {@link OpenTelemetry} instance and options for the hook.
+     */
+    public MetricsHook(final OpenTelemetry openTelemetry, final MetricHookOptions options) {
         final Meter meter = openTelemetry.getMeter(METER_NAME);
 
         activeFlagEvaluationsCounter =
@@ -76,7 +88,8 @@ public MetricsHook(final OpenTelemetry openTelemetry, final List<DimensionDescri
                 .setDescription("feature flag evaluation error counter")
                 .build();
 
-        dimensionDescriptions = Collections.unmodifiableList(dimensions);
+        dimensionDescriptions = Collections.unmodifiableList(options.getSetDimensions());
+        extractor = options.getAttributeSetter();
     }
 
 
@@ -110,6 +123,10 @@ public void after(HookContext ctx, FlagEvaluationDetails details, Map hints) {
             attributesBuilder.putAll(attributesFromFlagMetadata(details.getFlagMetadata(), dimensionDescriptions));
         }
 
+        if (extractor != null) {
+            attributesBuilder.putAll(extractor.apply(details.getFlagMetadata()));
+        }
+
         evaluationSuccessCounter.add(+1, attributesBuilder.build());
     }
 

hooks/open-telemetry/src/main/java/dev/openfeature/contrib/hooks/otel/TracesHook.java

@@ -3,11 +3,14 @@
 import dev.openfeature.sdk.FlagEvaluationDetails;
 import dev.openfeature.sdk.Hook;
 import dev.openfeature.sdk.HookContext;
+import dev.openfeature.sdk.ImmutableMetadata;
 import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.StatusCode;
 
 import java.util.Map;
+import java.util.function.Function;
 
 import static dev.openfeature.contrib.hooks.otel.OTelCommons.EVENT_NAME;
 import static dev.openfeature.contrib.hooks.otel.OTelCommons.flagKeyAttributeKey;
@@ -20,6 +23,7 @@
  */
 public class TracesHook implements Hook {
     private final boolean setSpanErrorStatus;
+    private final Function<ImmutableMetadata, Attributes> extractor;
 
     /**
      * Create a new OpenTelemetryHook instance with default options.
@@ -33,6 +37,7 @@ public TracesHook() {
      */
     public TracesHook(TracesHookOptions options) {
         setSpanErrorStatus = options.isSetSpanErrorStatus();
+        extractor = options.getDimensionExtractor();
     }
 
     /**
@@ -51,9 +56,18 @@ public TracesHook(TracesHookOptions options) {
         }
 
         String variant = details.getVariant() != null ? details.getVariant() : String.valueOf(details.getValue());
-        Attributes attributes = Attributes.of(flagKeyAttributeKey, ctx.getFlagKey(), providerNameAttributeKey,
-                ctx.getProviderMetadata().getName(), variantAttributeKey, variant);
-        currentSpan.addEvent(EVENT_NAME, attributes);
+
+        final AttributesBuilder attributesBuilder = Attributes.builder();
+
+        attributesBuilder.put(flagKeyAttributeKey, ctx.getFlagKey());
+        attributesBuilder.put(providerNameAttributeKey, ctx.getProviderMetadata().getName());
+        attributesBuilder.put(variantAttributeKey, variant);
+
+        if (extractor != null) {
+            attributesBuilder.putAll(extractor.apply(details.getFlagMetadata()));
+        }
+
+        currentSpan.addEvent(EVENT_NAME, attributesBuilder.build());
     }
 
     /**

hooks/open-telemetry/src/main/java/dev/openfeature/contrib/hooks/otel/TracesHookOptions.java

@@ -1,10 +1,14 @@
 package dev.openfeature.contrib.hooks.otel;
 
+import dev.openfeature.sdk.ImmutableMetadata;
+import io.opentelemetry.api.common.Attributes;
 import lombok.Builder;
 import lombok.Getter;
 
+import java.util.function.Function;
+
 /**
- * OpenTelemetry hook options.
+ * OpenTelemetry {@link TracesHook} options.
  */
 @Builder
 @Getter
@@ -14,4 +18,10 @@ public class TracesHookOptions {
      */
     @Builder.Default
     private boolean setSpanErrorStatus = false;
+
+    /**
+     * Custom callback to derive {@link Attributes} from flag evaluation metadata represented with
+     * {@link ImmutableMetadata}.
+     */
+    private Function<ImmutableMetadata, Attributes> dimensionExtractor;
 }

hooks/open-telemetry/src/test/java/dev/openfeature/contrib/hooks/otel/MetricsHookTest.java

@@ -200,4 +200,59 @@ public void finally_stage_validation() {
 
         assertThat(attributes.get(flagKeyAttributeKey)).isEqualTo("key");
     }
+
+    @Test
+    public void hook_option_validation(){
+        // given
+        MetricHookOptions hookOptions = MetricHookOptions.builder()
+                .attributeSetter(metadata -> Attributes.builder()
+                        .put("boolean", metadata.getBoolean("boolean"))
+                        .put("integer", metadata.getInteger("integer"))
+                        .put("long", metadata.getLong("long"))
+                        .put("float", metadata.getFloat("float"))
+                        .put("double", metadata.getDouble("double"))
+                        .put("string", metadata.getString("string"))
+                        .build())
+                .build();
+
+        final MetricsHook metricHook = new MetricsHook(telemetryExtension.getOpenTelemetry(), hookOptions);
+
+        final ImmutableMetadata metadata = ImmutableMetadata.builder()
+                .addBoolean("boolean", true)
+                .addInteger("integer", 1)
+                .addLong("long", 1L)
+                .addFloat("float", 1.0F)
+                .addDouble("double", 1.0D)
+                .addString("string", "string")
+                .build();
+
+        final FlagEvaluationDetails<String> evaluationDetails = FlagEvaluationDetails.<String>builder()
+                .flagKey("key")
+                .value("value")
+                .variant("variant")
+                .reason("STATIC")
+                .flagMetadata(metadata)
+                .build();
+
+        // when
+        metricHook.after(commonHookContext, evaluationDetails, null);
+        List<MetricData> metrics = telemetryExtension.getMetrics();
+
+        // then
+        assertThat(metrics).hasSize(1);
+
+        final MetricData metricData = metrics.get(0);
+        final Optional<LongPointData> pointData = metricData.getLongSumData().getPoints().stream().findFirst();
+        assertThat(pointData).isPresent();
+
+        final LongPointData longPointData = pointData.get();
+        final Attributes attributes = longPointData.getAttributes();
+
+        assertThat(attributes.get(AttributeKey.stringKey("string"))).isEqualTo("string");
+        assertThat(attributes.get(AttributeKey.doubleKey("double"))).isEqualTo(1.0D);
+        assertThat(attributes.get(AttributeKey.doubleKey("float"))).isEqualTo(1.0F);
+        assertThat(attributes.get(AttributeKey.longKey("long"))).isEqualTo(1L);
+        assertThat(attributes.get(AttributeKey.longKey("integer"))).isEqualTo(1);
+        assertThat(attributes.get(AttributeKey.booleanKey("boolean"))).isEqualTo(true);
+    }
 }

hooks/open-telemetry/src/test/java/dev/openfeature/contrib/hooks/otel/TracesHookTest.java

@@ -3,9 +3,11 @@
 import dev.openfeature.sdk.FlagEvaluationDetails;
 import dev.openfeature.sdk.FlagValueType;
 import dev.openfeature.sdk.HookContext;
+import dev.openfeature.sdk.ImmutableMetadata;
 import dev.openfeature.sdk.MutableContext;
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.api.trace.Span;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -159,4 +161,50 @@ void should_not_call_record_exception_when_no_active_span() {
         verifyNoInteractions(span);
     }
 
+    @Test
+    @DisplayName("should execute callback which populate span attributes")
+    void should_execute_callback_which_populate_span_attributes() {
+        FlagEvaluationDetails<String> details = FlagEvaluationDetails.<String>builder()
+                .variant("test_variant")
+                .value("variant_value")
+                .flagMetadata(ImmutableMetadata.builder()
+                        .addBoolean("boolean", true)
+                        .addInteger("integer", 1)
+                        .addLong("long", 1L)
+                        .addFloat("float", 1.0F)
+                        .addDouble("double", 1.0D)
+                        .addString("string", "string")
+                        .build())
+                .build();
+        mockedSpan.when(Span::current).thenReturn(span);
+
+        TracesHookOptions options = TracesHookOptions.builder()
+                .dimensionExtractor(metadata -> Attributes.builder()
+                        .put("boolean", metadata.getBoolean("boolean"))
+                        .put("integer", metadata.getInteger("integer"))
+                        .put("long", metadata.getLong("long"))
+                        .put("float", metadata.getFloat("float"))
+                        .put("double", metadata.getDouble("double"))
+                        .put("string", metadata.getString("string"))
+                        .build()
+                ).build();
+
+        TracesHook tracesHook = new TracesHook(options);
+        tracesHook.after(hookContext, details, null);
+
+        final AttributesBuilder attributesBuilder = Attributes.builder();
+        attributesBuilder.put(flagKeyAttributeKey, "test_key");
+        attributesBuilder.put(providerNameAttributeKey, "test provider");
+        attributesBuilder.put(variantAttributeKey, "test_variant");
+        attributesBuilder.put("boolean", true);
+        attributesBuilder.put("integer", 1);
+        attributesBuilder.put("long", 1L);
+        attributesBuilder.put("float", 1.0F);
+        attributesBuilder.put("double", 1.0D);
+        attributesBuilder.put("string", "string");
+
+
+        verify(span).addEvent("feature_flag", attributesBuilder.build());
+    }
+
 }