feat: implement new tracing hooks

lukas-reining · lukas-reining · commit d260a1d6dde5 · 2025-09-29T23:46:57.000+02:00
Signed-off-by: Lukas Reining &lt;lukas.reining@codecentric.de&gt;
diff --git a/libs/hooks/open-telemetry/README.md b/libs/hooks/open-telemetry/README.md
@@ -94,5 +94,5 @@ Run `nx package hooks-open-telemetry` to build the library.
 
 Run `nx test hooks-open-telemetry` to execute the unit tests via [Jest](https://jestjs.io).
 
-[otel-spec]: https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/feature-flags/
+[otel-spec]: https://opentelemetry.io/docs/specs/semconv/feature-flags/feature-flags-logs/
 [hook-concept]: https://openfeature.dev/docs/reference/concepts/hooks
diff --git a/libs/hooks/open-telemetry/package.json b/libs/hooks/open-telemetry/package.json
@@ -15,7 +15,8 @@
     "current-version": "echo $npm_package_version"
   },
   "peerDependencies": {
-    "@openfeature/server-sdk": "^1.13.0",
-    "@opentelemetry/api": ">=1.3.0"
+    "@openfeature/core": "^1.9.1",
+    "@opentelemetry/api": ">=1.3.0",
+    "@opentelemetry/api-events": "^0.202.0"
   }
 }
diff --git a/libs/hooks/open-telemetry/src/lib/conventions.ts b/libs/hooks/open-telemetry/src/lib/conventions.ts
@@ -1,4 +1,3 @@
-// see: https://opentelemetry.io/docs/specs/otel/logs/semantic_conventions/feature-flags/
 export const FEATURE_FLAG = 'feature_flag';
 export const EXCEPTION_ATTR = 'exception';
 
@@ -10,7 +9,13 @@ export const ERROR_TOTAL_NAME = `${FEATURE_FLAG}.evaluation_error_total`;
 export type EvaluationAttributes = { [key: `${typeof FEATURE_FLAG}.${string}`]: string | undefined };
 export type ExceptionAttributes = { [EXCEPTION_ATTR]: string };
 
-export const KEY_ATTR: keyof EvaluationAttributes = `${FEATURE_FLAG}.key`;
-export const PROVIDER_NAME_ATTR: keyof EvaluationAttributes = `${FEATURE_FLAG}.provider_name`;
-export const VARIANT_ATTR: keyof EvaluationAttributes = `${FEATURE_FLAG}.variant`;
-export const REASON_ATTR: keyof EvaluationAttributes = `${FEATURE_FLAG}.reason`;
+export const KEY_ATTR = `${FEATURE_FLAG}.key` as const;
+export const RESULT_VARIANT_ATTR = `${FEATURE_FLAG}.result.variant` as const;
+export const RESULT_VALUE_ATTR = `${FEATURE_FLAG}.result.value` as const;
+export const RESULT_REASON_ATTR = `${FEATURE_FLAG}.result.reason` as const;
+export const ERROR_TYPE_ATTR = `${FEATURE_FLAG}.error.type` as const;
+export const ERROR_MESSAGE_ATTR = `${FEATURE_FLAG}.error.message` as const;
+export const CONTEXT_ID_ATTR = `${FEATURE_FLAG}.context.id` as const;
+export const PROVIDER_NAME_ATTR = `${FEATURE_FLAG}.provider.name` as const;
+export const SET_ID_ATTR = `${FEATURE_FLAG}.set.name` as const;
+export const VERSION_ATTR = `${FEATURE_FLAG}.version` as const;
diff --git a/libs/hooks/open-telemetry/src/lib/metrics/metrics-hook.spec.ts b/libs/hooks/open-telemetry/src/lib/metrics/metrics-hook.spec.ts
@@ -1,17 +1,17 @@
-import type { BeforeHookContext, EvaluationDetails, HookContext } from '@openfeature/server-sdk';
-import { StandardResolutionReasons } from '@openfeature/server-sdk';
+import type { BeforeHookContext, EvaluationDetails, HookContext } from '@openfeature/core';
+import { StandardResolutionReasons } from '@openfeature/core';
 import opentelemetry from '@opentelemetry/api';
 import type { DataPoint, ScopeMetrics } from '@opentelemetry/sdk-metrics';
 import { MeterProvider, MetricReader } from '@opentelemetry/sdk-metrics';
 import {
   ACTIVE_COUNT_NAME,
   ERROR_TOTAL_NAME,
-  KEY_ATTR,
   PROVIDER_NAME_ATTR,
-  REASON_ATTR,
+  RESULT_REASON_ATTR,
   REQUESTS_TOTAL_NAME,
   SUCCESS_TOTAL_NAME,
-  VARIANT_ATTR,
+  RESULT_VARIANT_ATTR,
+  KEY_ATTR,
 } from '../conventions';
 import { MetricsHook } from './metrics-hook';
 import type { AttributeMapper } from '../otel-hook';
@@ -110,8 +110,8 @@ describe(MetricsHook.name, () => {
               point.value === 1 &&
               point.attributes[KEY_ATTR] === FLAG_KEY &&
               point.attributes[PROVIDER_NAME_ATTR] === PROVIDER_NAME &&
-              point.attributes[VARIANT_ATTR] === VARIANT &&
-              point.attributes[REASON_ATTR] === StandardResolutionReasons.STATIC,
+              point.attributes[RESULT_VARIANT_ATTR] === VARIANT &&
+              point.attributes[RESULT_REASON_ATTR] === StandardResolutionReasons.STATIC,
           ),
         ).toBeTruthy();
       });
@@ -143,8 +143,8 @@ describe(MetricsHook.name, () => {
               point.value === 1 &&
               point.attributes[KEY_ATTR] === FLAG_KEY &&
               point.attributes[PROVIDER_NAME_ATTR] === PROVIDER_NAME &&
-              point.attributes[VARIANT_ATTR] === VALUE.toString() &&
-              point.attributes[REASON_ATTR] === StandardResolutionReasons.STATIC,
+              point.attributes[RESULT_VARIANT_ATTR] === VALUE.toString() &&
+              point.attributes[RESULT_REASON_ATTR] === StandardResolutionReasons.STATIC,
           ),
         ).toBeTruthy();
       });
@@ -197,8 +197,8 @@ describe(MetricsHook.name, () => {
               point.value === 1 &&
               point.attributes[KEY_ATTR] === FLAG_KEY &&
               point.attributes[PROVIDER_NAME_ATTR] === PROVIDER_NAME &&
-              point.attributes[VARIANT_ATTR] === VARIANT &&
-              point.attributes[REASON_ATTR] === StandardResolutionReasons.STATIC &&
+              point.attributes[RESULT_VARIANT_ATTR] === VARIANT &&
+              point.attributes[RESULT_REASON_ATTR] === StandardResolutionReasons.STATIC &&
               // custom attributes should be present
               point.attributes[CUSTOM_ATTR_KEY_1] === CUSTOM_ATTR_VALUE_1 &&
               point.attributes[CUSTOM_ATTR_KEY_2] === CUSTOM_ATTR_VALUE_2,
@@ -243,8 +243,8 @@ describe(MetricsHook.name, () => {
               point.value === 1 &&
               point.attributes[KEY_ATTR] === FLAG_KEY &&
               point.attributes[PROVIDER_NAME_ATTR] === PROVIDER_NAME &&
-              point.attributes[VARIANT_ATTR] === VARIANT &&
-              point.attributes[REASON_ATTR] === StandardResolutionReasons.STATIC,
+              point.attributes[RESULT_VARIANT_ATTR] === VARIANT &&
+              point.attributes[RESULT_REASON_ATTR] === StandardResolutionReasons.STATIC,
           ),
         ).toBeTruthy();
       });
diff --git a/libs/hooks/open-telemetry/src/lib/metrics/metrics-hook.ts b/libs/hooks/open-telemetry/src/lib/metrics/metrics-hook.ts
@@ -1,11 +1,11 @@
-import type { BeforeHookContext, Logger } from '@openfeature/server-sdk';
+import type { BeforeHookContext, Logger } from '@openfeature/core';
 import {
   StandardResolutionReasons,
   type EvaluationDetails,
   type FlagValue,
-  type Hook,
+  type BaseHook,
   type HookContext,
-} from '@openfeature/server-sdk';
+} from '@openfeature/core';
 import type { Attributes, Counter, UpDownCounter } from '@opentelemetry/api';
 import { ValueType, metrics } from '@opentelemetry/api';
 import type { EvaluationAttributes, ExceptionAttributes } from '../conventions';
@@ -15,10 +15,10 @@ import {
   EXCEPTION_ATTR,
   KEY_ATTR,
   PROVIDER_NAME_ATTR,
-  REASON_ATTR,
+  RESULT_REASON_ATTR,
   REQUESTS_TOTAL_NAME,
   SUCCESS_TOTAL_NAME,
-  VARIANT_ATTR,
+  RESULT_VARIANT_ATTR,
 } from '../conventions';
 import type { OpenTelemetryHookOptions } from '../otel-hook';
 import { OpenTelemetryHook } from '../otel-hook';
@@ -39,7 +39,7 @@ const ERROR_DESCRIPTION = 'feature flag evaluation error counter';
  *
  * See {@link https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/feature-flags/}
  */
-export class MetricsHook extends OpenTelemetryHook implements Hook {
+export class MetricsHook extends OpenTelemetryHook implements BaseHook {
   protected name = MetricsHook.name;
   private readonly evaluationActiveUpDownCounter: UpDownCounter<EvaluationAttributes>;
   private readonly evaluationRequestCounter: Counter<EvaluationAttributes>;
@@ -83,8 +83,8 @@ export class MetricsHook extends OpenTelemetryHook implements Hook {
     this.evaluationSuccessCounter.add(1, {
       [KEY_ATTR]: hookContext.flagKey,
       [PROVIDER_NAME_ATTR]: hookContext.providerMetadata.name,
-      [VARIANT_ATTR]: evaluationDetails.variant ?? evaluationDetails.value?.toString(),
-      [REASON_ATTR]: evaluationDetails.reason ?? StandardResolutionReasons.UNKNOWN,
+      [RESULT_VARIANT_ATTR]: evaluationDetails.variant ?? evaluationDetails.value?.toString(),
+      [RESULT_REASON_ATTR]: evaluationDetails.reason ?? StandardResolutionReasons.UNKNOWN,
       ...this.safeAttributeMapper(evaluationDetails?.flagMetadata || {}),
     });
   }
diff --git a/libs/hooks/open-telemetry/src/lib/otel-hook.ts b/libs/hooks/open-telemetry/src/lib/otel-hook.ts
@@ -1,23 +1,56 @@
-import type { FlagMetadata, Logger } from '@openfeature/server-sdk';
+import type {
+  EvaluationDetails,
+  FlagMetadata,
+  FlagValue,
+  HookContext,
+  Logger,
+  TelemetryAttribute,
+} from '@openfeature/core';
+import { createEvaluationEvent } from '@openfeature/core';
 import type { Attributes } from '@opentelemetry/api';
 
+type EvaluationEvent = { name: string; attributes: Attributes };
+type TelemetryAttributesNames = [keyof typeof TelemetryAttribute][number] | string;
+
 export type AttributeMapper = (flagMetadata: FlagMetadata) => Attributes;
 
+export type EventMutator = (event: EvaluationEvent) => EvaluationEvent;
+
 export type OpenTelemetryHookOptions = {
   /**
    * A function that maps OpenFeature flag metadata values to OpenTelemetry attributes.
+   * This can be used to add custom attributes to the telemetry event.
+   * Note: This function is applied after the excludeAttributes option.
    */
   attributeMapper?: AttributeMapper;
+
+  /**
+   * Exclude specific attributes from being added to the telemetry event.
+   * This is useful for excluding sensitive information, or reducing the size of the event.
+   * By default, no attributes are excluded.
+   * Note: This option is applied before the attributeMapper and eventMutator options.
+   */
+  excludeAttributes?: TelemetryAttributesNames[];
+
+  /**
+   * Takes a telemetry event and returns a telemetry event.
+   * This can be used to filter out attributes that are not needed or to add additional attributes.
+   * Note: This function is applied after the attributeMapper and excludeAttributes options.
+   */
+  eventMutator?: EventMutator;
 };
 
 /**
  * Base class that does some logging and safely wraps the AttributeMapper.
  */
 export abstract class OpenTelemetryHook {
-  protected safeAttributeMapper: AttributeMapper;
   protected abstract name: string;
 
-  constructor(options?: OpenTelemetryHookOptions, logger?: Logger) {
+  protected attributesToExclude: TelemetryAttributesNames[];
+  protected safeAttributeMapper: AttributeMapper;
+  protected safeEventMutator: EventMutator;
+
+  protected constructor(options?: OpenTelemetryHookOptions, logger?: Logger) {
     this.safeAttributeMapper = (flagMetadata: FlagMetadata) => {
       try {
         return options?.attributeMapper?.(flagMetadata) || {};
@@ -26,5 +59,31 @@ export abstract class OpenTelemetryHook {
         return {};
       }
     };
+    this.safeEventMutator = (event: EvaluationEvent) => {
+      try {
+        return options?.eventMutator?.(event) ?? event;
+      } catch (err) {
+        logger?.debug(`${this.name}: error in eventMutator, ${err.message}, ${err.stack}`);
+        return event;
+      }
+    };
+    this.attributesToExclude = options?.excludeAttributes ?? [];
+  }
+
+  protected toEvaluationEvent(
+    hookContext: Readonly<HookContext>,
+    evaluationDetails: EvaluationDetails<FlagValue>,
+  ): EvaluationEvent {
+    const { name, attributes } = createEvaluationEvent(hookContext, evaluationDetails);
+    const customAttributes = this.safeAttributeMapper(evaluationDetails.flagMetadata);
+
+    for (const attributeToExclude of this.attributesToExclude) {
+      delete attributes[attributeToExclude];
+    }
+
+    return this.safeEventMutator({
+      name,
+      attributes: { ...attributes, ...customAttributes },
+    });
   }
 }
diff --git a/libs/hooks/open-telemetry/src/lib/traces/tracing-hook.spec.ts b/libs/hooks/open-telemetry/src/lib/traces/tracing-hook.spec.ts
@@ -1,4 +1,5 @@
-import type { EvaluationDetails, HookContext } from '@openfeature/server-sdk';
+import type { EvaluationDetails, HookContext } from '@openfeature/core';
+import { MapHookData } from '@openfeature/core';
 
 const addEvent = jest.fn();
 const recordException = jest.fn();
@@ -12,7 +13,7 @@ jest.mock('@opentelemetry/api', () => ({
 }));
 
 // Import must be after the mocks
-import { TracingHook } from './tracing-hook';
+import { SpanEventTracingHook } from './tracing-hook';
 
 describe('OpenTelemetry Hooks', () => {
   const hookContext: HookContext = {
@@ -30,9 +31,10 @@ describe('OpenTelemetry Hooks', () => {
     defaultValue: true,
     flagValueType: 'boolean',
     logger: console,
+    hookData: new MapHookData(),
   };
 
-  let tracingHook: TracingHook;
+  let tracingHook: SpanEventTracingHook;
 
   afterEach(() => {
     jest.clearAllMocks();
@@ -41,7 +43,7 @@ describe('OpenTelemetry Hooks', () => {
   describe('after stage', () => {
     describe('no attribute mapper', () => {
       beforeEach(() => {
-        tracingHook = new TracingHook();
+        tracingHook = new SpanEventTracingHook();
       });
 
       it('should use the variant value on the span event', () => {
@@ -52,7 +54,7 @@ describe('OpenTelemetry Hooks', () => {
           flagMetadata: {},
         };
 
-        tracingHook.after(hookContext, evaluationDetails);
+        tracingHook.finally(hookContext, evaluationDetails);
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
@@ -68,7 +70,7 @@ describe('OpenTelemetry Hooks', () => {
           flagMetadata: {},
         };
 
-        tracingHook.after(hookContext, evaluationDetails);
+        tracingHook.finally(hookContext, evaluationDetails);
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
@@ -83,7 +85,7 @@ describe('OpenTelemetry Hooks', () => {
           value: 'already-string',
           flagMetadata: {},
         };
-        tracingHook.after(hookContext, evaluationDetails);
+        tracingHook.finally(hookContext, evaluationDetails);
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
@@ -101,15 +103,15 @@ describe('OpenTelemetry Hooks', () => {
           flagMetadata: {},
         };
 
-        tracingHook.after(hookContext, evaluationDetails);
+        tracingHook.finally(hookContext, evaluationDetails);
         expect(addEvent).not.toBeCalled();
       });
     });
 
     describe('attribute mapper configured', () => {
       describe('no error in mapper', () => {
         beforeEach(() => {
-          tracingHook = new TracingHook({
+          tracingHook = new SpanEventTracingHook({
             attributeMapper: (flagMetadata) => {
               return {
                 customAttr1: flagMetadata.metadata1,
@@ -132,7 +134,7 @@ describe('OpenTelemetry Hooks', () => {
             },
           };
 
-          tracingHook.after(hookContext, evaluationDetails);
+          tracingHook.finally(hookContext, evaluationDetails);
 
           expect(addEvent).toBeCalledWith('feature_flag', {
             'feature_flag.key': 'testFlagKey',
@@ -147,7 +149,7 @@ describe('OpenTelemetry Hooks', () => {
 
       describe('error in mapper', () => {
         beforeEach(() => {
-          tracingHook = new TracingHook({
+          tracingHook = new SpanEventTracingHook({
             attributeMapper: () => {
               throw new Error('fake error');
             },
@@ -166,7 +168,7 @@ describe('OpenTelemetry Hooks', () => {
             },
           };
 
-          tracingHook.after(hookContext, evaluationDetails);
+          tracingHook.finally(hookContext, evaluationDetails);
 
           expect(addEvent).toBeCalledWith('feature_flag', {
             'feature_flag.key': 'testFlagKey',
diff --git a/libs/hooks/open-telemetry/src/lib/traces/tracing-hook.ts b/libs/hooks/open-telemetry/src/lib/traces/tracing-hook.ts

Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,8 @@`
`15`	`15`	`"current-version": "echo $npm_package_version"`
`16`	`16`	`},`
`17`	`17`	`"peerDependencies": {`
`18`		`- "@openfeature/server-sdk": "^1.13.0",`
`19`		`- "@opentelemetry/api": ">=1.3.0"`
	`18`	`+ "@openfeature/core": "^1.9.1",`
	`19`	`+ "@opentelemetry/api": ">=1.3.0",`
	`20`	`+ "@opentelemetry/api-events": "^0.202.0"`
`20`	`21`	`}`
`21`	`22`	`}`