feat: update otel hook to use new semconv

lukas-reining · lukas-reining · commit dbeac9be5121 · 2025-09-07T23:47:28.000+02:00
Signed-off-by: Lukas Reining &lt;lukas.reining@codecentric.de&gt;
diff --git a/libs/hooks/open-telemetry/package.json b/libs/hooks/open-telemetry/package.json
@@ -15,7 +15,7 @@
     "current-version": "echo $npm_package_version"
   },
   "peerDependencies": {
-    "@openfeature/server-sdk": "^1.13.0",
+    "@openfeature/core": "^1.0.0",
     "@opentelemetry/api": ">=1.3.0"
   }
 }
diff --git a/libs/hooks/open-telemetry/src/lib/conventions.ts b/libs/hooks/open-telemetry/src/lib/conventions.ts
@@ -1,4 +1,7 @@
 // see: https://opentelemetry.io/docs/specs/otel/logs/semantic_conventions/feature-flags/
+import type { FlagValue } from '@openfeature/core';
+import type { AttributeValue } from '@opentelemetry/api';
+
 export const FEATURE_FLAG = 'feature_flag';
 export const EXCEPTION_ATTR = 'exception';
 
@@ -10,7 +13,35 @@ 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;
+
+export const ALL_EVENT_ATTRS = [
+  KEY_ATTR,
+  PROVIDER_NAME_ATTR,
+  RESULT_VARIANT_ATTR,
+  RESULT_VALUE_ATTR,
+  RESULT_REASON_ATTR,
+  ERROR_TYPE_ATTR,
+  ERROR_MESSAGE_ATTR,
+  CONTEXT_ID_ATTR,
+  SET_ID_ATTR,
+  VERSION_ATTR,
+];
+
+export type TracingEventAttributeKey = (typeof ALL_EVENT_ATTRS)[number];
+
+export type TracingEvent = {
+  [K in Exclude<TracingEventAttributeKey, 'feature_flag.key' | 'feature_flag.result.value'>]?: string;
+} & {
+  [KEY_ATTR]: string;
+  [RESULT_VALUE_ATTR]?: FlagValue;
+} & { [key: string]: AttributeValue | undefined };
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,5 +1,5 @@
-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';
@@ -8,10 +8,10 @@ import {
   ERROR_TOTAL_NAME,
   KEY_ATTR,
   PROVIDER_NAME_ATTR,
-  REASON_ATTR,
+  RESULT_REASON_ATTR,
   REQUESTS_TOTAL_NAME,
   SUCCESS_TOTAL_NAME,
-  VARIANT_ATTR,
+  RESULT_VARIANT_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,4 +1,4 @@
-import type { FlagMetadata, Logger } from '@openfeature/server-sdk';
+import type { FlagMetadata, Logger } from '@openfeature/core';
 import type { Attributes } from '@opentelemetry/api';
 
 export type AttributeMapper = (flagMetadata: FlagMetadata) => Attributes;
@@ -17,7 +17,7 @@ export abstract class OpenTelemetryHook {
   protected safeAttributeMapper: AttributeMapper;
   protected abstract name: string;
 
-  constructor(options?: OpenTelemetryHookOptions, logger?: Logger) {
+  protected constructor(options?: OpenTelemetryHookOptions, logger?: Logger) {
     this.safeAttributeMapper = (flagMetadata: FlagMetadata) => {
       try {
         return options?.attributeMapper?.(flagMetadata) || {};
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 { ErrorCode } from '@openfeature/core';
 
 const addEvent = jest.fn();
 const recordException = jest.fn();
@@ -13,6 +14,7 @@ jest.mock('@opentelemetry/api', () => ({
 
 // Import must be after the mocks
 import { TracingHook } from './tracing-hook';
+import { ALL_EVENT_ATTRS } from '../conventions';
 
 describe('OpenTelemetry Hooks', () => {
   const hookContext: HookContext = {
@@ -56,28 +58,52 @@ describe('OpenTelemetry Hooks', () => {
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
-          'feature_flag.provider_name': 'testProvider',
-          'feature_flag.variant': 'enabled',
+          'feature_flag.provider.name': 'testProvider',
+          'feature_flag.result.variant': 'enabled',
         });
       });
 
-      it('should use a stringified value as the variant value on the span event', () => {
+      it('should use the error values on the span event', () => {
         const evaluationDetails: EvaluationDetails<boolean> = {
+          value: false,
           flagKey: hookContext.flagKey,
-          value: true,
+          errorCode: ErrorCode.PROVIDER_FATAL,
+          errorMessage: 'fake error message',
           flagMetadata: {},
         };
 
         tracingHook.after(hookContext, evaluationDetails);
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
-          'feature_flag.provider_name': 'testProvider',
-          'feature_flag.variant': 'true',
+          'feature_flag.provider.name': 'testProvider',
+          'feature_flag.error.type': ErrorCode.PROVIDER_FATAL.toLowerCase(),
+          'feature_flag.error.message': 'fake error message',
+        });
+      });
+
+      it('should not call addEvent because there is no active span', () => {
+        getActiveSpan.mockReturnValueOnce(undefined);
+        const evaluationDetails: EvaluationDetails<boolean> = {
+          flagKey: hookContext.flagKey,
+          value: true,
+          variant: 'enabled',
+          flagMetadata: {},
+        };
+
+        tracingHook.after(hookContext, evaluationDetails);
+        expect(addEvent).not.toBeCalled();
+      });
+    });
+
+    describe('with value attribute', () => {
+      beforeEach(() => {
+        tracingHook = new TracingHook({
+          includeAttributes: ALL_EVENT_ATTRS,
         });
       });
 
-      it('should set the value without extra quotes if value is already a string', () => {
+      it('should set the value', () => {
         const evaluationDetails: EvaluationDetails<string> = {
           flagKey: hookContext.flagKey,
           value: 'already-string',
@@ -87,22 +113,29 @@ describe('OpenTelemetry Hooks', () => {
 
         expect(addEvent).toBeCalledWith('feature_flag', {
           'feature_flag.key': 'testFlagKey',
-          'feature_flag.provider_name': 'testProvider',
-          'feature_flag.variant': 'already-string',
+          'feature_flag.provider.name': 'testProvider',
+          'feature_flag.result.value': 'already-string',
         });
       });
 
-      it('should not call addEvent because there is no active span', () => {
-        getActiveSpan.mockReturnValueOnce(undefined);
+      it('should use the error values and value on the span event', () => {
         const evaluationDetails: EvaluationDetails<boolean> = {
+          value: false,
           flagKey: hookContext.flagKey,
-          value: true,
-          variant: 'enabled',
+          errorCode: ErrorCode.PROVIDER_FATAL,
+          errorMessage: 'fake error message',
           flagMetadata: {},
         };
 
         tracingHook.after(hookContext, evaluationDetails);
-        expect(addEvent).not.toBeCalled();
+
+        expect(addEvent).toBeCalledWith('feature_flag', {
+          'feature_flag.key': 'testFlagKey',
+          'feature_flag.provider.name': 'testProvider',
+          'feature_flag.result.value': false,
+          'feature_flag.error.type': ErrorCode.PROVIDER_FATAL.toLowerCase(),
+          'feature_flag.error.message': 'fake error message',
+        });
       });
     });
 
@@ -136,8 +169,8 @@ describe('OpenTelemetry Hooks', () => {
 
           expect(addEvent).toBeCalledWith('feature_flag', {
             'feature_flag.key': 'testFlagKey',
-            'feature_flag.provider_name': 'testProvider',
-            'feature_flag.variant': 'enabled',
+            'feature_flag.provider.name': 'testProvider',
+            'feature_flag.result.variant': 'enabled',
             customAttr1: 'one',
             customAttr2: 2,
             customAttr3: true,
@@ -170,8 +203,8 @@ describe('OpenTelemetry Hooks', () => {
 
           expect(addEvent).toBeCalledWith('feature_flag', {
             'feature_flag.key': 'testFlagKey',
-            'feature_flag.provider_name': 'testProvider',
-            'feature_flag.variant': 'enabled',
+            'feature_flag.provider.name': 'testProvider',
+            'feature_flag.result.variant': 'enabled',
           });
         });
       });
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,7 @@`
`15`	`15`	`"current-version": "echo $npm_package_version"`
`16`	`16`	`},`
`17`	`17`	`"peerDependencies": {`
`18`		`- "@openfeature/server-sdk": "^1.13.0",`
	`18`	`+ "@openfeature/core": "^1.0.0",`
`19`	`19`	`"@opentelemetry/api": ">=1.3.0"`
`20`	`20`	`}`
`21`	`21`	`}`